Main Content

Configure File Storage for Users in MATLAB Online Server

A storage profile is a specification defined by the MATLAB® Online Server™ administrator that determines the drives, directories, and files available to the resource (MATLAB) after users sign on. The storage profiles are defined in the storage section of your matlab-pool.yaml file. These profiles are mounted when the user signs in and the remote resource (MATLAB) is allocated to them.

The login information provides more data regarding the user at the time of mounting the profile to the Storage service (part of the MATLAB pod). This information is used to resolve and mount user-specific directories.

Storage profiles allow you to specify this dynamic configuration through the use of placeholders. These placeholders are resolved dynamically while the directories are mounted with the same information from a user who has signed in (from the authnz service). For more information about placeholders, see Placeholders.

Depending on your configuration of storage profiles, additional training for the MATLAB user might be required. If the MATLAB user saves data in the persistent folders or mounts, then when the user signs into a new session, all saved data is restored. However, data that the user stores in a nonpersistent folder, such as /tmp, does not persist to the next session. Familiarize your users with the concept of data persistence so that they know which folders to use for data they want to preserve between sessions.

Before mounting storage profiles, to optimize MATLAB performance for your end users, consult with your file system owner or cloud provider on the appropriate file system and storage configuration options to use. Performance can vary based on several factors, including:

  • The storage protocol used

  • The configuration options of your cloud storage vendor, such as the amount of IOPS (input/output operations per second) and bandwidth selected

  • The disk-intensity of your MATLAB end user workflows

Profile Specification

AttributeDefault ValueOptionalNote
name""No Name of the storage profile.
startDirectory"/"Yes Start directory (user path of the MATLAB user) after the storage profile is mounted. See example and more below this table.
restrictNavigationOutsideMountsfalseYes If true, MATLAB users are not able to navigate (cd) to other directories other than those specified in mounts and MATLAB directory.
mounts<Nil>Yes Directories to be mounted and then made available to the MATLAB user (see Mount Specifications).
addons<Nil>Yes Directory where MATLAB add-ons are stored (see Specification for Add-Ons).
allowedGroups<Nil>Yes

List of the groups that user should belong to so that they can use this profile

These groups are compared against the list of groups that are configured through authnz (see Placeholders).

  • If allowedGroups is empty (default), the storage profile can be mounted by any user.

  • If there are multiple values in allowedGroups, a user that is part of any group listed can mount this storage profile.

  • Also include in allowedGroups the exact group name that is returned in the SubjectAuthResponse.

    For example, in the LDAP scenario, the group name is the full Distinguished Name (DN): (CN=group2,OU=Group,OU=Mail,DC=ad,DC=domain,DC=com)

In YAML format:

storage:
  profiles:  
    - name: "<name>"  
      mounts:
        "<list of mounts>"  
      startDirectory: "<start directory>"  
      restrictNavigationOutsideMounts: <true/false>  
      addons:  
        directory: "<addons directory>"
      allowedGroups:
      - "<name_of_group_1>"
      - "<name_of_group_2>" 

startDirectory—User session and Preferences directory. This folder contains the preferences, settings, history, and layout files associated with the user. For more about MATLAB user settings, see the MATLAB documentation in the Help Center.

MATLAB Online Server provides the ability to store the MATLAB preferences and some of the session information as part of the storage profile configuration.

For each storage profile, startDirectory can be customized. This field sets the session directory when the user signs into MATLAB Online Server.

When this directory is persistent, the history, layout preferences, and more will be automatically restored when the user next signs in.

Format:

startDirectory: "/home/${subject.subjectId}"

Specification for Add-Ons

AttributeDefault ValueOptionalNote
directory <startDirectory>/MATLAB Add-OnsYesDirectory where MATLAB add-ons are stored.

Mount Specifications

AttributeDefault ValueOptionalNote
name""NoName of the mount.
mountPath""No

Path of the mount. This information is available to the MATLAB user as the mounted path, after the user signs in.

mountPath must be a directory that the MATLAB user has access to and not a protected Linux® directory, such as "/bin", "/etc", or "/home". To specify a mount path within the home directory of the MATLAB user, use Placeholders. For example: "/home/${subject.subjectId}".

type""No Type of the mount. Based on the type, the mount properties can vary. For more information, see Mount Types.
permissionType""NoType of the permissions that are given to the mounted directory after the user has signed in. Based on the permission type, the mount properties can vary. For more information, see Mount Types.

createIfNotExist

falseYes

Dynamically create folders while provisioning the storage for MATLAB user, if the folder does not exist with the same UID permissions of the user.

This attribute applies only when you use dynamic placeholders and when the permissionType is set to User.

timeoutInSeconds120YesNumber of seconds that the server waits before terminating a running executable.

Mount Types

MATLAB Online Server supports the following mount types:

  • "empty" — Create an empty directory that is deleted after the user signs out.

  • "host" — Mount a directory from the node's host.

  • "nfs" — Mount a directory from the network file system (NFS).

  • "delegated" — Mount a directory by calling an executable.

  • "pvc" — Mount a persistent volume claim (PVC) that is available on the Kubernetes® cluster.

To disable certain mount types, in the resource.yaml YAML file, add or update the storage field and specify the disallowedMountTypes subfield. For example, this sample YAML disables the delegated and PVC mount types.

storage:
  disallowedMountTypes: 
    - "delegated"
    - "pvc"

Empty

The Empty (empty) mount type creates an empty directory. This storage is ephemeral storage, meaning that after a user signs out of the session, all data inside the directory is deleted permanently.

This mount type does not require any extra properties.

In YAML format:

storage:  
  profiles:  
    - name: "<name>"  
      mounts:  
        - name: "code"  
          mountPath: "/code"  
          type: "empty"
          permissionType: "<permission type>"  
      startDirectory: "<start directory>"  
      restrictNavigationOutsideMounts: <true/false>  
      addons:  
        directory: "<addons directory>"

Host

The Host (host) mount type mounts a directory from the Nodes host. This mount type expects the directory (hostPath) to be present on the Node; otherwise, the MATLAB pod does not start.

This mount type has these extra properties:

  • hostPath (required) — The folder being mounted

  • subPath (optional) — The specific folder within hostPath that is available to the MATLAB end user.

    When using dynamic placeholders to specify user-specific folders, the folder must already exist or you must create the folders dynamically by adding createIfNotExist: true to the storage mount. See Dynamic Folder Creation.

    The folders before the placeholder in subPath must be writable by MATLAB Online Server. For example, if subPath is set to "/exports/${subject.subjectId}", then /exports must be writable.

In YAML format:

storage:  
  profiles:  
     - name: "<name>"  
        mounts:  
        - name: "node_folder"  
          mountPath: "/share" 
          hostPath: "/share" 
          type: "host"
          subPath: "/exports/${subject.subjectId}"
          permissionType: "<permission type>"  
        startDirectory: "<start directory>"  
        restrictNavigationOutsideMounts: <true/false>  
        addons:  
          directory: "<addons directory>"

NFS

The NFS (nfs) mount type mounts an NFS directory and then makes it available to the MATLAB user.

This mount type expects that the NFS server allows mounting the NFS directories onto the MATLAB pods. The NFS administrator might need to allow access to the NFS server by the Kubernetes cluster, through the NFS exports list.

This mount type requires the following extra properties:

  • server (required) — Name of NFS server

  • subPath (required) — The specific folder within server that is available to the MATLAB end user.

    When using dynamic placeholders to specify user-specific folders, the folder must already exist or you must create the folders dynamically by adding createIfNotExist: true to the storage mount. See Dynamic Folder Creation.

    The folders before the placeholder in subPath must be writable by MATLAB Online Server. For example, if subPath is set to "/exports/home/${subject.subjectId}", then /exports/home must be writable.

  • mountOptions (required) — Options for configuring the NFS mount. For mount option details, see https://linux.die.net/man/5/nfs. To view the supported NFS versions, see Software Requirements.

In YAML format:

storage:  
  profiles:  
    - name: "<name>"  
      mounts:  
        - name: "nfsHome"  
          mountPath: "/share" 
          type: "nfs" 
          server: "nfs" 
          subPath: "/exports/home/${subject.subjectId}"  
          mountOptions:
"rw,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,acregmin=60
0,acregmax=600,acdirmin=600,acdirmax=600,hard,nocto,noacl,proto=tcp,ti
meo=600,retrans=2,mountproto=tcp,local_lock=none,nolock"
         permissionType: "<permission type>"
      startDirectory: "<start directory>"
      restrictNavigationOutsideMounts: <true/false>
      addons:
        directory: "<addons directory>"

Delegated

The Delegated (delegated) mount type mounts a drive or directory using a specified executable. You can use this executable to customize the storage mount using options not natively supported by the other mount types. For example, your executable can mount an NFS drive and specify mount options using the Common Internet File System (CIFS) protocol, which the "nfs" mount type does not support.

By default, this mount type is not enabled. To enable it, add or update the storage field of your resource.yaml file to specify the disallowedMountTypes subfield, and do not include the "delegated" option in this subfield. For example, this sample YAML field enables all mount types.

storage:
  disallowedMountTypes: []

In addition to the default storage mount properties, this mount type has this additional property:

  • args (required) — List of one or more command-line arguments used to call the executable. The first argument is the path to the executable file. Specify any additional options used to call the executable in subsequent arguments.

In YAML format:

storage:  
  profiles:  
    - name: "<profile name>"  
      mounts:  
        - name: "<mount name>"  
          mountPath: "<mount path>"  
          type: "delegated"
          permissionType: "none"
          args:
          -  "/opt/matlabonlineserver/my_mount_script.sh"
          timeoutInSeconds: 10

The executable that you write must support these options:

  • --mos-mount-dir <folder> argument that specifies the folder being mounted

  • start operation that mounts the folder

  • stop operation that unmounts the folder

Your MATLAB Online Server installation includes a sample customizable shell script for mounting an NFS drive. The script is located in the resource proxy Docker® image, which controls the storage layer for MATLAB users. It is located at this path:

mos-resource-proxy-image/main/src/main/scripts/example_mount.sh

The example_mount.sh script has these contents.

#!/bin/bash
 
usage()
{
    echo "usage   : example_mount [[-h]]"
    echo "example : ./example_mount.sh or ./example_mount.sh -h or"
    echo "./example_mount.sh start --mos-mount-dir /tmp or ./example_mount.sh stop --mos-mount-dir /tmp"
}
 
function run() {
    echo "$@"
    $@
}
 
MOS_MOUNT_DIR=""
MOUNT_OPERATION=""
NFS_SERVER="myserver"
NFS_SUBPATH="mysubpath"
 
while [ "$1" != "" ]; do
    case $1 in
        -h | --help )                        usage
                                             exit
                                             ;;
        --mos-mount-dir )                    shift
                                             MOS_MOUNT_DIR=$1
                                             ;;
        start )                              MOUNT_OPERATION=$1
                                             ;;
        stop )                               MOUNT_OPERATION=$1
                                             ;;
        # Other arguments can be processed the same way
        * )                                  usage
                                             exit 1
    esac
    shift
done
 
if [ -z "$MOS_MOUNT_DIR" ]
then
echo "Mount directory is empty"
exit 1
fi
 
case "${MOUNT_OPERATION}" in
    "start")
        echo "Starting mount operation on directory ${MOS_MOUNT_DIR}"
        run mkdir -p "$MOS_MOUNT_DIR"
        run sudo mount -t nfs -o rw,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,acregmin=600, \
acregmax=600,acdirmin=600,acdirmax=600,hard,nocto,noacl,proto=tcp,timeo=600,retrans=2,mountproto=tcp, \
local_lock=none,nolock ${NFS_SERVER}:${NFS_SUBPATH} "${MOS_MOUNT_DIR}"
        ;;
    "stop")
        echo "Stopping mount operation on directory ${MOS_MOUNT_DIR}"
        run sudo umount "${MOS_MOUNT_DIR}"
        ;;
    *)
        echo "Not a supported mount operation"
        exit 1
        ;;
esac
 
exit 0

In this script, you can customize the NFS_SERVER and NFS_SUBPATH variables to set the NFS folder you want to mount. Placeholders for specifying user names are supported. For more details, see Placeholders. Sample variable values are:

NFS_SERVER = "nfs"
NFS_SUBPATH = "exports/home/${subject.subjectId}"

By default, the executables you write can run the mount, unmount, chown, and chmod commands without requiring a password. If your executable uses other commands that normally require a password, you can customize the resource proxy image to run these commands without a password.

Caution

Disabling password prompts for commands that normally require sudo administration privileges can be a security risk.

Suppose you want your executable to run mkdir without having to enter a password on folders that are normally password protected. You can write a Dockerfile to disable the password prompt in the resource proxy image and then rebuild the image.

This example assumes you are using Docker as your container management tool. If you are using Podman instead, replace docker with podman in the commands shown.

  1. Navigate to the folder containing your script.

  2. Create a file named Dockerfile (no extension) and open it for editing.

    touch Dockerfile && nano Dockerfile

  3. Create a backup of the resource proxy image using this Docker command. Run this command as a single line. Update the image names with the name of your resource proxy image.

    sudo docker tag containers.mathworks.com/matlab-online-server/mos-resource-proxy-image:1.13.0-bullseye
      containers.mathworks.com/matlab-online-server/mos-resource-proxy-image:1.13.0-bullseye-backup
    
  4. Copy the following lines of code into your Dockerfile and customize them for your executable.

    • FROM — Specify the name of the resource proxy image you are referencing.

    • COPY — Specify the name of your script and the location where you want to copy the script to. In your storage profile, the first item in the "args" field references this location.

    • RUN — Specify the commands for which you want to disable the password requirements. To disable passwords on additional commands, add more RUN lines. These lines update the sudo policy on your machine. For more details, see Sudoers Manual.

    • USER — Temporarily switch to the root user to perform the RUN operation. mwuser is the default user for the resource proxy.

    FROM containers.mathworks.com/matlab-online-server/mos-resource-proxy-image:1.13.0-bullseye-backup
    
    USER root
    
    COPY myscript.sh /opt/matlabonlineserver/myscript.sh
    
    RUN chmod +x /opt/matlabonlineserver/mount.sh
    RUN echo "mwuser  ALL=(ALL) NOPASSWD: /usr/bin/mkdir" >> /etc/sudoers
    
    USER mwuser

  5. Build and tag the image. For example, this sample tag inserts the word "delegated" at the end to record the change.

    sudo docker build . --tag containers.mathworks.com/matlab-online-server/mos-resource-proxy-image:1.13.0-bullseye-delegated
  6. If you are using a remote registry, build and push the customized image to your Docker registry using these docker commands.

    sudo docker push . containers.mathworks.com/matlab-online-server/mos-resource-proxy-image:1.13.0-bullseye-delegated
    
  7. In the matlab-pool.yaml file, add or update the "images" field with the customized resource-proxy image. For example:

    images:
      resourceProxy:
        image: mos-resource-proxy-image
        tag: 1.13.0-bullseye-delegated
  8. Undeploy and redeploy the matlab-pool.yaml file to apply your changes.

    ./mosadm undeploy
    ./mosadm deploy

Persistent Volume Claim (PVC)

PVC (pvc) mount type mounts a Persistent Volume Claim that is available on the Kubernetes cluster and makes it available to the MATLAB user.

Refer to the following link for detailed information on Persistent Volumes: https://kubernetes.io/docs/concepts/storage/persistent-volumes.

Note

MATLAB Online Server expects that the Persistent Volume Claim is allowed for:

  • Mounting onto the MATLAB pods (same PVC)

    • Some PV types might restrict the scaling based on the PV configuration

  • Read and write files

  • Retaining data after exiting the session (using persistentVolumeReclaimPolicy)

If Persistent Volume or Persistent Volume Claim is created in Kubernetes with a different configuration, you must reconfigure the object to satisfy the above conditions.

This mount type requires the following extra properties:

  • claimName

    • The name of the Persistent Volume Claim

  • subPath

    The specific folder within the data volume (Persistent Volume Claim) that is available to the MATLAB end user.

    When using dynamic placeholders to specify user-specific folders, the folder must already exist or you must create the folders dynamically by adding createIfNotExist: true to the storage mount. See Dynamic Folder Creation.

    The folders before the placeholder in subPath must be writable by MATLAB Online Server. For example, if subPath is set to "/exports/home/${subject.subjectId}", then /exports/home must be writable.

These extra properties are shown in YAML format in the following example:

storage:
  profiles: 
    - name: "<name>" 
      mounts: 
        - name: "home" 
          mountPath: "/share" 
          type: "pvc" 
          claimName: "<pvc name>" 
          subPath: "/exports/home/${subject.subjectId}" 
          permissionType: "<permission type>"
      startDirectory: "<start directory>" 
      restrictNavigationOutsideMounts: <true/false> 
      addons: 
        directory: "<addons directory>"

When using a Persistent Volume Claim, keep these points in mind:

  • You can specify the same Persistent Volume Claim more than once in a storage profile. Within the mounts field, specify each claim as a separate mount.

  • If you specify the same Persistent Volume Claim in more than one storage profile, each claim must have a different mount name.

  • The same Persistent Volume Claims defined in the storage profile are mounted in all MATLAB pods.

  • The storage resources request that is defined in the Persistent Volume or Persistent Volume Claim must be sufficient to meet the entire storage needs for all users.

Permission Types

The following permission types are supported: None, Fixed, and User.

None

The None (none) permission type performs a mount with default access to the MATLAB process only.

This permission type is ideal for empty mount types (ephemeral storage) or anonymous read-only directories that are mounted.

This permission type does not require any extra properties.

In YAML format:

storage:  
  profiles:  
    - name: "<name>"  
      mounts:  
        - name: "code"  
          mountPath: "/code"  
          type: "empty"  
          permissionType: "none"  
      startDirectory: "<start directory>"  
      restrictNavigationOutsideMounts: <true/false>  
      addons:  
        directory: "<addons directory>"

Fixed

The Fixed (fixed) permission type performs a mount and then shares the directory with the same permissions that are specified (uid, gid) to the MATLAB process only.

This permission type is ideal for shared read-only directories.

This permission type requires the following extra properties:

  • uid — User ID

  • gid — Primary group ID

In YAML format:

storage:  
  profiles:  
    - name: "<name>"  
      mounts:  
      - name: "public"  
        mountPath: "/public"  
        type: "nfs"  
        server: "nfs"  
        subPath: "/exports/nfs_share"  
        mountOptions: 
"ro,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,acreg
min=600,acregmax=600,acdirmin=600,acdirmax=600,hard,nocto,noacl,
proto=tcp,timeo=600,retrans=2,sec=sys,mountproto=tcp,local_lock=
none,nolock"  
        permissionType: "fixed"  
        uid: "1001"  
        gid: "1000"  
      startDirectory: "<start directory>"  
      restrictNavigationOutsideMounts: <true/false>  
      addons:  
        directory: "<addons directory>"

User

The User (user) permission type performs a mount and then shares the directory with the same permissions as that of the user (uid, gid) to the MATLAB process only if the placeholders are resolved. For more information, see Placeholders.

This permission type is ideal for mounting user-specific directories, such as an NFS home folder, which is readable and writable by the signed-in user only.

This permission type requires the following extra properties:

  • uid — User ID

  • gid — Primary group ID

In YAML format:

storage:  
  profiles:  
  - name: "<name>"  
    mounts:  
      - name: "public"  
        mountPath: "/public"  
        type: "nfs"  
        server: "nfs"  
        subPath: "/exports/home/${subject.subjectId}"  
        mountOptions: 
"rw,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,acreg
min=600,acregmax=600,acdirmin=600,acdirmax=600,hard,nocto,noacl,
proto=tcp,timeo=600,retrans=2,mountproto=tcp,local_lock=none,nol
ock"  
        permissionType: "user"  
        uid: "${subject.uid}"  
        gid: "${subject.gid}"  
    startDirectory: "<start directory>"  
    restrictNavigationOutsideMounts: <true/false>  
    addons:  
      directory: "<addons directory>"

Disallow UIDs

MATLAB Online Server includes a security feature that disallows certain UIDs to create storage mounts.

You can add a configurable list of UIDs that are not allowed to set up the storage permissions. For example, if a user with UID 0 signs in, the permissions on the bound folder are given the root permissions (as UID = 0); this feature disallows this permission binding for UID 0.

The following shows the default list of disallowed UIDs (in YAML format); you can override the values with your specific disallowed UIDs:

storage: 
  disallowedUids: 
    - "0" 
    - "1000600715" 
    - "1000600903" 
    - "1000600912" 

Dynamic Folder Creation

Currently, MATLAB Online Server provides a way to mount the file system available to the MATLAB user with the dynamic placeholders support of storage profiles. This feature extends the ability to create the folders automatically in their storage mount with the appropriate user permissions.

With the createIfNotExist attribute, you can dynamically create folders while provisioning the storage for the user, if the folder does not exist with the same UID permissions of the user.

For example, assume the following storage profile is defined and is applicable for the user when they sign in:

storage:
  profiles:  
    - name: "<name>"  
      mounts:  
        - name: "public"  
          mountPath: "/public" 
           type: "nfs"  
           server: "nfs"  
           subPath: "/exports/home/${subject.subjectId}"  
           mountOptions: 
"rw,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,acregmin=600,acregm
ax=600,acdirmin=600,acdirmax=600,hard,nocto,noacl,proto=tcp,timeo=600,retrans=
2,mountproto=tcp,local_lock=none,nolock"  
          permissionType: "user"  
          uid: "${subject.uid}"  
          gid: "${subject.uid}" 
          createIfNotExist: true
      startDirectory: "<start directory>"  
      restrictNavigationOutsideMounts: <true/false>  
      addons:  
        directory: "<addons directory>" 
  • The placeholder "${subject.subjectId}" is resolved to the username, for example, username1, when a user signing in to MATLAB Online Server as username1. The NFS server and the subpath "nfs:/exports/home" are mounted by the storage service.

  • If the folder /exports/home/username1 exists in nfsserver "nfs", then the storage service uses that folder. Otherwise, the folder is created after placeholder resolution with the permissions "${subject.uid}" (for example, 3904).

  • The folder permissions on the Linux file system (in the NFS server) are:

    ls -al /exports/home 
    drwxr-xr-x 1     3904  3904   20 Feb 18 19:13 /exports
    /home/username1/

Placeholders

Placeholders are temporary markers for values that are resolved dynamically while the directories are mounted during storage setup.

For more information on the authnz IdP (Identify Provider) configuration and the Subject response, see Configure User Authentication in MATLAB Online Server.

A sample response from authnz follows. In this case, with the same information for the signed-in user from the authnz service.

{  
   mwtype: "authnz/SubjectAuthResponse",  
   subject: {  
      subjectId: "username1",  
      displayName: "username1",  
      groups: [
      "group1",
      "group2"
    ],  
      extra:{  
         uid:[  
            "3904"  
         ],  
         gid:[  
            "3904"  
         ]  
      },  
      idp:"ldap"  
   },  
   authToken: "xxxxxxx-xxxxxxxx-xxxxxx",  
   authenticated: true  
}

From the above response, the following placeholders can be resolved:

  • subject.subjectId

  • subject.displayName

  • subject.groups

  • subject.uid

  • subject.gid

As another example, consider a storage unit with one NFS directory per user that must be mounted, where:

  • Each user has a different home directory that is differentiated by the user name.

  • The home directory of each user is locked to their UID and GID.

The storage profile can be constructed as follows:

storage:  
  profiles:  
    - name: "nfsHome"
      startDirectory: "/home/${subject.subjectId}"  
      mounts:  
        - name: "home"  
          permissionType: "user"
          mountPath: "/home/${subject.subjectId}"  
          uid: "${subject.uid}"  
          gid: "${subject.gid}"  
          type: "nfs"
          server: "nfs"  
          subPath: "/exports/home/${subject.subjectId}"  
          mountOptions: 
"rw,relatime,vers=3,rsize=1048576,wsize=1048576,namlen=255,acreg
min=600,acregmax=600,acdirmin=600,acdirmax=600,hard,nocto,noacl,
proto=tcp,timeo=600,retrans=2,mountproto=tcp,local_lock=none,nol
ock"  
      restrictNavigationOutsideMounts: false

Note that mountPath cannot be started with a placeholder.

Storage Profiles: Examples

The following examples demonstrate creating storage profiles based on the following types of storage systems (backed by Kubernetes Persistent Volumes):

  • NFS

  • AWS®

    • EBS

    • EFS

  • Azure®

    • Azure Files

Results of these examples may vary based on variable information, such as Kubernetes version, features on the Kubernetes cluster, updates by the cloud provider that are more recent that these examples, and so on.

Each example includes the following:

  • Prerequisites:

  • Create Persistent Volume Claim

    • Provides a sample YAML file that can be used to create the Persistent Volume Claim and other dependent objects, if required.

    • Provides a command to create these objects in Kubernetes.

  • Storage Profile

    • A storage profile is a specification defined by the MATLAB Online Server administrator that determines how and which drives, directories, and files are available to the resource (MATLAB) after users sign on.

    • The storage profiles are defined in the MATLAB Pool configuration:

      <OVERRIDES_DIR>/<cluster>/<namespace>/matlab-pool.yaml
    • After MATLAB Online Server is deployed successfully with the new storage profiles, when a MATLAB user signs in to MATLAB Online Server, the working directory of the user will be /home/<username>.

  • Cleanup (optional)

    • Provides commands for removing the Persistent Volume Claim and the dependent Kubernetes objects, if needed.

NFS - PVC Storage Profile

The following example provides instructions to create a Persistent Volume Claim where the data is stored in an NFS server. This newly created Persistent Volume Claim in MATLAB Online Server can provide data persistence to the MATLAB user upon signing in.

  1. Prerequisites:

    The cluster must install the required NFS CSI driver. There are many Kubernetes CSI drivers that are available, and the instructions differ based on which is installed.

    This example uses the default NFS CSI driver created by the Kubernetes project:

    1. Add helm repo:

      helm repo add csi-driver-nfs https://raw.githubusercontent.com/kubernetes-csi/csi-driver-nfs/master/charts
    2. Install CSI driver:

      helm install csi-driver-nfs csi-driver-nfs/csi-driver-nfs --namespace kube-system
  2. Create Persistent Volume Claim using YAML and kubectl

    • Save the following lines in a YAML file, for example, nfs-pv.yaml.

      apiVersion: "v1"
      kind: "PersistentVolume"
      metadata:
        name: "pv-example-nfs"
      spec:
        capacity:
          storage: "10Gi"
        accessModes:
          - ReadWriteMany
        persistentVolumeReclaimPolicy: "Retain"
        mountOptions:
          - relatime
          - vers=3
          - rsize=1048576
          - wsize=1048576
          - namlen=255
          - acregmin=600
          - acregmax=600
          - acdirmin=600
          - acdirmax=600
          - hard
          - nocto
          - noacl
          - proto=tcp
          - timeo=600
          - retrans=2
          - mountproto=tcp
          - local_lock=none
          - nolock
        csi:
          driver: "nfs.csi.k8s.io"
          readOnly: false
          volumeHandle: "unique-volumeid"  # make sure it's a unique id in the cluster
          volumeAttributes:
            server: "examplenfsserver"
            share: "/local-ssd/nfs_pv"
      ---
      apiVersion: "v1"
      kind: "PersistentVolumeClaim"
      metadata:
        name: "pvc-example-nfs"
      spec:
        accessModes:
          - ReadWriteMany
        resources:
          requests:
            storage: "10Gi"
        volumeName: "pv-example-nfs"
        storageClassName: ""
      
    • Create the Persistent Volume and Persistent Volume Claim using the following command:

      kubectl apply --namespace <namespace-name> -f nfs-pv.yaml
  3. Storage Profile

    In your overrides/<cluster-name>/<namespace-name>/matlab-pool.yaml file, add these lines to mount the volume in your home directory.

    storage:
      profiles:
        - name: "home"
          mounts:
            - name: "home"
              mountPath: "/home/${subject.subjectId}"
              type: "pvc"
              claimName: "pvc-example-nfs"
              subPath: "/data/${subject.subjectId}"
              createIfNotExist: true
              permissionType: "user"
              uid: "${subject.uid}"
              gid: "${subject.uid}"
          startDirectory: "/home/${subject.subjectId}"
    
  4. Cleanup

    1. Undeploy all applications that are using Persistent Volume. For undeploying MATLAB Online Server, matlab-pool, use the following command:

      ./mosadm undeploy matlab-pool
    2. Remove Persistent Volume and Persistent Volume Claim:

      kubectl delete -f
    3. Uninstall the NFS CSI driver:

      helm uninstall csi-driver-nfs -n kube-system

EBS (Elastic Block Storage) PVC Storage Profile

The following example provides instructions to create a Persistent Volume Claim where the data is stored in an AWS EBS volume, and for using this newly created Persistent Volume Claim in MATLAB Online Server to provide data persistence to the MATLAB user upon signing in.

  1. Prerequisites:

    The cluster must install the required EBS CSI Driver. To install the driver, refer to the information at Amazon EBS CSI driver.

    You might need to set permissions to allow MATLAB Online Server to create the EBS volumes and attach them to the Kubernetes cluster through IAM roles.

  2. Create Persistent Volume Claim using YAML and kubectl

    1. Save the following lines in a YAML file, for example, ebs-pv.yaml.

      apiVersion: "v1"
      kind: "PersistentVolumeClaim"
      metadata:
        name: "pvc-example-ebs-eks"
      spec:
        accessModes:
          - ReadWriteOnce
        storageClassName: "gp2"
        resources:
          requests:
            storage: "100Gi"
    2. Create Persistent Volume and Persistent Volume Claim using the command:

      kubectl apply --namespace <namespace-name> -f ebs-pv.yaml

      Note that you do not need to create a Persistent Volume explicitly; the GP2 storage class automatically provisions an EBS volume when a Persistent Volume Claim is created.

  3. Storage Profile

    In your overrides/<cluster-name>/<namespace-name>/matlab-pool.yaml file, add these lines to mount the volume in your home directory.

    storage:
      profiles:
        - name: "home"
          mounts:
            - name: "home"
              mountPath: "/home/${subject.subjectId}"
              type: "pvc"
              claimName: "pvc-example-ebs-eks"
              subPath: "/data/${subject.subjectId}"
              createIfNotExist: true
              permissionType: "user"
              uid: "${subject.uid}"
              gid: "${subject.uid}"
          startDirectory: "/home/${subject.subjectId}"
  4. Cleanup

    For more information, see Amazon EBS CSI driver.

EFS (Elastic File Storage) PVC Storage Profile

The following example provides instructions to create a Persistent Volume Claim where the data is stored in an AWS EFS volume, and for using this newly created Persistent Volume Claim in MATLAB Online Server to provide data persistence to the MATLAB user upon signing in.

  1. Prerequisites:

    The cluster must install the required EFS CSI Driver. To install the driver, refer to the information at Amazon EFS CSI driver.

    You might need to set permissions to allow MATLAB Online Server to create the EFS volumes and attach them to the Kubernetes cluster through IAM roles.

  2. Create Persistent Volume Claim using YAML and kubectl.

    1. Save the following lines in a YAML file, for example, efs-pv.yaml.

      apiVersion: "storage.k8s.io/v1"
      kind: "StorageClass"
      metadata:
        name: "efs-sc"
      provisioner: "efs.csi.aws.com"
      ---
      apiVersion: "v1"
      kind: "PersistentVolume"
      metadata:
        name: "pvc-example-efs-eks"
      spec:
        capacity:
          storage: "5Gi"
        volumeMode: "Filesystem"
        accessModes:
          - ReadWriteMany
        persistentVolumeReclaimPolicy: "Retain"
        storageClassName: "efs-sc"
        csi:
          driver: "efs.csi.aws.com"
          volumeHandle: "<EFS Volume ID>"  # fs-8416d972
      ---
      apiVersion: "v1"
      kind: "PersistentVolumeClaim"
      metadata:
        name: "pvc-example-efs-eks"
      spec:
        accessModes:
          - ReadWriteMany
        storageClassName: "efs-sc"
        resources:
          requests:
            storage: "5Gi"
    2. Create Persistent Volume and Persistent Volume Claim using the following command:

      kubectl --namespace <namespace-name> apply -f az-files-pv.yaml
  3. Storage Profile

    In your overrides/<cluster-name>/<namespace-name>/matlab-pool.yaml file, add these lines to mount the volume in your home directory.

    storage:
      profiles:
        - name: "home"
          mounts:
            - name: "home"
              mountPath: "/home/${subject.subjectId}"
              type: "pvc"
              claimName: "pvc-example-efs-eks"
              subPath: "/data/${subject.subjectId}"
              createIfNotExist: true
              permissionType: "user"
              uid: "${subject.uid}"
              gid: "${subject.uid}"
          startDirectory: "/home/${subject.subjectId}"
  4. Cleanup

    For more information, see Amazon EBS CSI driver.

Azure Files PVC Storage Profile

The following example provides instructions to create a Persistent Volume Claim where the data is stored in an Azure Files volume, and for using this newly created Persistent Volume Claim in MATLAB Online Server to provide data persistence to the MATLAB user upon signing in.

  1. Prerequisites

    The cluster must install the required Azure Files CSI Driver. To install the driver, see Use Azure Files Container Storage Interface (CSI) drivers in Azure Kubernetes Service (AKS).

    You must allow permissions for MATLAB Online Server to access the Azure Files volumes and attach them to the Kubernetes cluster. Create a Kubernetes secret with the appropriate credential information (storage account and the storage key):

    kubectl create secret generic --namespace <namespace-name> az-files-example-secret --from-literal=azurestorageaccountname=<STORAGEACCT> --from-literal=azurestorageaccountkey=<STORAGEKEY>
  2. Create Persistent Volume Claim using YAML and kubectl.

    To provide access to the Azure Files, perform the following steps:

    1. Save the following lines in a YAML file, for example, az-files-pv.yaml.

      apiVersion: "v1"
      kind: "PersistentVolume"
      metadata:
        name: "pv-example-az-files"
      spec:
        capacity:
          storage: "5Gi"
        accessModes:
          - ReadWriteMany
        azureFile:
          secretName: "az-files-example-secret"
          shareName: "<AZ-Files-Share-Name>"
          readOnly: false
        mountOptions:
        - dir_mode=0777
        - file_mode=0777
        - uid=1000
        - gid=1000
        - mfsymlinks
        - nobrl
      ---
      apiVersion: "v1"
      kind: "PersistentVolumeClaim"
      metadata:
        name: "pvc-example-az-files"
      spec:
        accessModes:
          - ReadWriteMany
        storageClassName: ""
        resources:
          requests:
            storage: "5Gi"
    2. Create Persistent Volume and Persistent Volume Claim using the following command:

      kubectl --namespace <namespace-name> apply -f az-files-pv.yaml
  3. Storage Profile

    In your overrides/<cluster-name>/<namespace-name>/matlab-pool.yaml file, add these lines to mount the volume in your home directory.

    storage:
      profiles:
        - name: "home"
          mounts:
            - name: "home"
              mountPath: "/home/${subject.subjectId}"
              type: "pvc"
              claimName: "pvc-example-az-files"
              subPath: "/data/${subject.subjectId}"
              createIfNotExist: true
              permissionType: "user"
              uid: "${subject.uid}"
              gid: "${subject.uid}"
          startDirectory: "/home/${subject.subjectId}"
  4. Cleanup

    For more information, see Use Azure Files Container Storage Interface (CSI) drivers in Azure Kubernetes Service (AKS).

Related Topics