Main Content

mosadm run-smoke-tests

Run smoke tests on MATLAB Online Server

Since R2020a

collapse all in page

    Syntax

    mosadm run-smoke-tests
    mosadm run-smoke-tests option1 ... optionN

    Description

    mosadm run-smoke-tests runs smoke tests on MATLAB® Online Server™.

    Smoke tests reveal simple failures severe enough to impact operations. The smoke test tool that comes with MATLAB Online Server runs a set of tests against a MATLAB Online Server implementation. The tool returns information on installation setup, Kubernetes® elements, and the MATLAB Online Server microservices. The information provided by these smoke tests can help focus troubleshooting strategies for MATLAB Online Server.

    Note

    To run smoke tests, verify that your system meets the prerequisites specified in Smoke Test Prerequisites

    For details on interpreting the results, see Address Smoke Test Failures

    example

    mosadm run-smoke-tests option1 ... optionN runs smoke tests using the specified configuration options.

    Note

    mosadm run-smoke-tests interacts with Docker®. If you do not have sudo administration privileges for Docker, then this command also requires sudo.

    example

    Examples

    collapse all

    sudo ./mosadm run-smoke-tests
    YYYY/MM/DD hh:mm:ss Smoke-Tests---------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss    Commands---------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss       docker : PASS
YYYY/MM/DD hh:mm:ss       kubectl : PASS
YYYY/MM/DD hh:mm:ss       helm : PASS
YYYY/MM/DD hh:mm:ss    Commands : PASS
YYYY/MM/DD hh:mm:ss    -----------------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss    Properties-------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss       DomainBaseLookup : PASS
YYYY/MM/DD hh:mm:ss       DomainBaseSecurelyReachable : PASS
YYYY/MM/DD hh:mm:ss    Properties : PASS
...
    sudo ./mosadm run-smoke-tests --verbose
    YYYY/MM/DD hh:mm:ss Smoke-Tests---------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss    Commands---------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss       docker--------------------------------------------------------------------
YYYY/MM/DD hh:mm:ss          docker version : Client:
                              Version:           20.10.12
                              API version:       1.41
                              Go version:        go1.17.3
                              Git commit:        20.10.12-0ubuntu4
                              Built:             Mon Mar  7 17:10:06 YYYY
                              OS/Arch:           linux/amd64
                              Context:           default
                              Experimental:      true
                              ...

    Input Arguments

    collapse all

    One or more configuration options, specified as strings corresponding to valid configuration options from these tables.

    Specific to mosadm run-smoke-tests

    OptionDescription
    --container-log-tail-lines numLines

    Number of lines from the end of the container log to display.

    Default: 100

    --deployment-image-registry registryName

    Image registry to use for the deployment.

    Example: registry.yourcompany.com

    --deployment-image-repository repositoryName

    Image repository to use for the deployment images.

    Example: mathworks

    --domain-base domainBaseName

    Domain where MATLAB Online Server is running. By default, domainBaseName is the value of the DOMAIN_BASE property of the install.config file.

    --image-flavor imageFlavorName

    Container image flavor, specified as debian or rhel.

    Default: debian

    --license-port portNum

    Port number used to connect to MathWorks® License Manager. Specify portNum as a numeric string representing a valid port number.

    Default: 8080

    --no-certificate-check

    If the certificate deployed at MATLAB Online Server does not match its domain, many tests fail. Specify this argument to ignore this certificate mismatching.

    --no-secure-http

    If no certificate is deployed at MATLAB Online Server, run tests that require HTTP calls using only nonsecure HTTP. Use this option to check whether MATLAB Online Server is deployed properly before deploying the appropriate certificate. If you specify this option, then mosadm run-smoke-tests ignores the --no-certificate-check option.

    --no-terminal-colors

    Skip printing output using the default terminal colors to aid accessibility.

    --skip-tests testName1 ... testNameN

    Names of tests to be skipped.

    --time-out numSeconds

    Number of seconds to wait to start running tests before canceling the operation.

    Default: 5

    Common to All mosadm Commands

    OptionDescription

    --charts-dir chartsDir

    Name of the MATLAB Online Server charts folder to use. This folder contains the Helm® charts of the server.

    Specify chartsDir as an absolute path or a path relative to the MATLAB Online Server root folder mosRoot.

    Example: matlab_online_server/charts.

    Default: mosRoot/charts

    --data-dir dataDir

    Name of the MATLAB Online Server data folder to use.

    Specify dataDir as an absolute path or a path relative to the MATLAB Online Server root folder mosRoot.

    Example: matlab_online_server/data.

    Default: mosRoot/data

    --dry-run

    Print out the commands that would have run without this option specified but do not run the operation. Specify this option to test that the operation produces the expected results before actually executing it.

    --help, -h, help

    		Output help for mosadm run-smoke-tests to the command line.

    --kube-config configFilePath

    Path to the Kubernetes cluster configuration file. Specify configFilePath as an absolute path or a path relative to the MATLAB Online Server root folder mosRoot.

    Example: /etc/kubernetes/admin.conf

    By default, configFilePath is empty and Kubernetes obtains the cluster configuration from the KUBECONFIG environment variable (if specified) or the ~/.kube/config file. If you run mosadm run-smoke-tests with sudo, then ~/.kube/config is equivalent to /root/.kube/config.

    --mos-root rootDir

    MATLAB Online Server root folder, specified as an absolute path or a path relative to the current folder, that is, the folder in which you can run mosadm commands.

    Default: . (current folder)

    --overrides-dir overridesDir

    Name of the MATLAB Online Server overrides folder to use.

    Specify overridesDir as an absolute path or a path relative to the MATLAB Online Server root folder, mosRoot.

    Example: matlab_online_server/overrides

    Default: mosRoot/overrides

    --quiet, -q

    Print only the most useful or relevant output from the mosadm run-smoke-tests command.

    --skip-log-file

    Skip creating the install.log file and logging data about the mosadm run-smoke-tests operation to this file.

    --skip-prompt, -y

    Force acceptance of the terms of use for the mosadm run-smoke-tests and skip any command-line prompts normally provided when calling this command.

    --tmp-dir tempDirName

    Name of MATLAB Online Server temporary folder to use.

    Specify tempDirName as an absolute path or a path relative to the temporary folder.

    By default, mosadm run-smoke-tests generates a new temporary folder every time you run the command.

    --verbose

    Output extra details about the mosadm run-smoke-tests operation to the command line.

    More About

    collapse all

    Smoke Test Prerequisites

    Single Node

    • Set and export your test username and password environment variables MOS_TEST_USERNAME and MOS_TEST_PASSWORD. Their default values are admin and password, respectively. The username and password should be valid credentials for signing in to your MATLAB Online Server session via the browser.

    • If you have installed MATLAB Online Server using the mosadm command, mosadm applies the correct Kube-Config and properly sets the environment variable KUBECONFIG.

    Managed Kubernetes (EKS, GKE, AKS, …)

    • Set and export your test username and password environment variables MOS_TEST_USERNAME and MOS_TEST_PASSWORD. Their default values are admin and password, respectively.

    • Make sure that you can access your Kubernetes cluster via kubectl.

    • Your ~/.kube/config should point to your cluster and namespace Kube-Config file, or your KUBECONFIG environment variable should be set to the right path of your Kube-Config file. KUBECONFIG has priority over ~/.kube/config.

    Address Smoke Test Failures

    Before proceeding with troubleshooting failures shown by the smoke tests, make sure that the prerequisites stated in the MATLAB Online Server Administrator Guide are satisfied.

    Examine the results of the smoke tests and determine if all tests passed or if there are failures that you must investigate.

    If you get a PASS result on all smoke tests, then you have properly deployed MATLAB Online Server, and you are ready to access it from your browser.

    If you get a FAIL for one or more sub smoke tests, then you must find the root cause of their failures before proceeding further.

    The smoke tests are divided into several parts, where each part has a subset of tests that target a specific part of configuration or behavior of your local setup, Kubernetes configuration, or MATLAB Online Server setup.

    If you get a FAIL on any sub smoke test, rerun the smoke tests with the argument –verbose. This argument gives you more details on the failures.

    Commands Tests

    The commands tests check if the commands docker, kubectl, and helm run properly from the machine on which you are running the mosadm command. If the –verbose option is enabled, you get more details on their versions.

    If any of the subtests fails, you can manually check if the related command (docker, kubect,l or helm) is installed on your machine and properly working.

    Properties Tests

    The properties checks focus on tests related to your MATLAB Online Server domain.

    • DomainBaseLookup checks if your domain is reachable securely via HTTPS.

    • DomainBaseSecurelyReachable checks if your domain is resolvable to an IP address.

    • DomainBaseValidateCertificate checks if your domain SSL certificate matches your domain name.

    While the MATLAB Online Server installation instructions specify that you have a valid SSL certificate that matches your MATLAB Online Server domain name, you may not have it initially ready. However, you can still run the smoke tests.

    If you don’t have a valid SSL certificate or you have one but it does not match your domain (for example, you may have a self-signed certificate), you can have the smoke test bypass the certificate requirement by passing the no-secure-http and no-certificate-check arguments to the smoke tests option:

    mosadm run-smoke-tests --no-secure-http --no-certificate-check

    Docker Tests

    The Docker tests check properties related your local Docker environment. The test checks for the Docker Root Directory disk space (refer to Hardware Requirements for details on disk space requirements).

    If the available disk space under this directory disk partition is low, then that might be a root cause for some deployment failures. Consider increasing this disk space, or re-install or re-configure Docker to use a Root Directory under a partition with more disk space.

    Kubernetes Tests

    The Kubernetes tests run a set of tests related to your Kubernetes cluster.

    • GetKubernetesClient checks if the test can communicate with your Kubernetes cluster. If this test fails, then make sure that your KUBECONFIG environment variable (or ~/.kube/config file) is set properly and you can access it successfully from your installation machine using the kubectl command.

    • CheckKubernetesNamespace verifies that your configured namespace, which defaults to mathworks, exists under your Kubernetes cluster. If the configured namespace is not present under your Kubernetes cluster, then your MATLAB Online Server is not deployed properly or is deployed under the wrong namespace.

    • GetPodsList displays all pods under your configured namespace. This test is mainly informative. It displays all existing pods under your Kubernetes namespace.

    • MOS-Core-ServicesPodsAreReady lists only the MATLAB Online Server core service pods. If a pod is running properly, the test shows the status READY next to the service. Otherwise, the test shows which underlying container is failing, along with any error messages that apply.

    MATLAB Online Server

    MATLAB Online Server runs targeted tests against each MATLAB Online™ core service.

    • AuthNZ checks if the authentication (authnz) service can authenticate users via their usernames and passwords. Under Smoke Test Prerequisites, you set two environment variables: MOS_TEST_USERNAME and MOS_TEST_PASSWORD. These variables store the valid username and password, respectively, for accessing your MATLAB Online Server from the browser. These variables default to admin and password.

      If this AuthNZ test fails, even if those environment variables are set properly, then check if the License test is failing. If this is the case, first fix the License service and then re-run the smoke tests. If the License test passes and the AuthNZ test is still failing, then check the AuthNZ service logs for further troubleshooting.

    • CoreUI, Gateway, MATLABPoolUI and Resource run a set of internal MATLAB Online Server tests. Like AuthNZ, if any of these services tests fails, first check if the License service is passing its test before troubleshooting any of them.

    • License checks if the MATLAB Online Server License service is responding to requests. If this test shows the status PASS but other MATLAB Online Server services are still failing their tests, check if your network license manager server is accessible, through its ports, from your Kubernetes pods. To check if a server is accessible via specific port, you can use the netcat (nc) command.

    Also check if your license file (license.dat) contains your MATLAB licenses as well as your MATLAB Online Server license.

    • Help tests if the Help content is accessible by MATLAB Online Server users. Even if these tests are failing, it does affect the remaining MATLAB Online Server services.

    If you get many MATLAB Online Server services smoke tests failing, start by troubleshooting the License service and then proceed further with the remaining services.

    As a best practice, after fixing each single failed sub smoke test, re-run all smoke tests. Some services depend on others, and fixing one of them, like the License service, can in many cases fix other failures.

    If you continue to see errors in some sub smoke tests of some MATLAB Online Server services, check their logs (see Configure Log Shipping), as these files often provide useful information on the root causes of such failures.

    If you are still experiencing failures after applying the troubleshooting suggestions, perform the following:

    1. Save the logs folder, generated by the smoke tests, as a zip file.

    2. Run the command sudo ./mosadm gather-system-info. This command generates the file install.log.

    3. Contact MathWorks Support.

    Version History

    Introduced in R2020a

    See Also

    Topics