Configuring MLz

The initial configuration of ML for IBM z/OS® refers to the tasks of verifying prerequisite software levels, verifying system environment variable settings, creating metadata objects, creating runtime environments, and setting up MLz. You can use the ML for IBM z/OS configuration tool to quickly complete these tasks.

Before you begin

Procedure

  1. Locate the configtool.sh script in the $IML_INSTALL_DIR/iml-utilities/configtool directory.

    The configtool.sh script will prepare for the launch of the ML for IBM z/OS configuration tool. You can use the script to start and stop the configuration tool, and to retrieve the access token required by the tool.

  2. Run the configtool.sh script with the start option: 
    ./configtool.sh start
    Tip: If you already have a MLz system configured under $IML_HOME, you can enter Y to continue the configuration process, or enter N to exit. If you enter Y, the old system under $IML_HOME will be cleaned; If you enter N to exit the configuration process, you can update your $IML_HOME to another location, then run ./configtool.sh start command again.
  3. When prompted, enter the IP address or host name, and the port number of the z/OS system where the configuration tool will run.

    The port number that you enter during this step is saved in $IML_HOME/iml-config/imltool_logs/tool-error.log.

    The script will start the process for the configuration tool. After the process is successfully started, the script will display the full URL of the web user interface (UI) of the configuration tool and the access token required by the web UI.

  4. Copy and paste the URL into the address field of your browser and press Enter to launch the ML for IBM z/OS configuration tool welcome page.
    Tip: ML for IBM z/OS supports the standard or desktop version of Mozilla Firefox and Google Chrome. See Supported browsers for ML for IBM z/OS user interfaces for more details.
  5. Copy and paste the access token into the access token field on the UI and click Start to configure MLz.
    Tip: Take note and save the access token in case you need to sign in to the configuration tool again. Alternatively, run the configtool.sh script with the gettoken option (./configtool.sh gettoken) to retrieve the token.
  6. On the Configuration options page, we support two version of the configuration: MLz Core and MLz Enterprise.
    MLz Core is an easily configuration edition of MLz with a smaller footprint and fewer dependencies. This configuration contains the following features:
    • RESTful API support for model management and deployment
    • Inference capability for SparkML and PMML models
    MLz Enterprise is the most expansive configuration of the MLz product. This configuration contains the following features:
    • RESTful and native interface
    • ONNX compiler service
    • SparkML, PMML, Python, and ONNX scoring runtimes
    • Model development environment
    • Trustworthy AI
    Select the MLz configuration you would like to set up, then click Next to start configuring the MLz.
  7. On the Environment readiness page, verify that your system and environment are ready for configuration.

    The configuration tool checks that required software, including Spark, node.js, bash, and Java™, is at the required level and that environment variables are properly set on your z/OS system.

    Tip: The configuration tool also checks the initial space allocation to the zFS file system of the $IML_HOME directory. If the size of the zFS file system is too small and an error is reported, use the zfsadm grow command to increase the aggregate as long as there is enough space on the volume. See zfsadm grow for details.
  8. In the Instance details section, specify the Instance name for the MLz instance. To proceed to the next page, you must have READ access to the SAF profile ALN.ROLE.<MLz instance name>.SYSADM.
    For example, if you enter MLZINST1 as the instance name, you must create the SAF profile ALN.ROLE.MLZINST1.SYSADM in the XFACILIT class. For more information, see Managing MLz users and privileges.
  9. On the Metadata repository page, select embedded database or specify a Db2 for z/OS system and schema name for MLz metadata objects.

    If the embedded database is selected as the Metadata repository, click Next directly to continue to the next step.

    If you plan to enable Core HA (on the Services page) or Scoring HA (on the Scoring service page), Db2 for z/OS system must be selected as the Metadata repository. Specify the host IP or name, TCP port, location, JDBC properties, and Db2 special registers for your Db2 for z/OS system. See Configuring MLz to connect to Db2 using an SSL secure port for more details.

    Note: Starting with v3.2.0 release (APAR PH69959), MLz uses the z/OS Cloud Data Access (CDA) cloud credential storage to store the Db2 credentials used by the repository service. As a result, the Metadata repository page no longer prompts for Db2 credentials. For more information, see step 2 in Configuring MLz to use CDA cloud credential storage.

    The configuration tool uses the schema you specify to check for metadata objects. If the required metadata objects do not exist under the specified schema, create them as described in Creating metadata objects for the Machine Learning for IBM z/OS Enterprise Edition repository service, then come back to this step. Alternatively, click Create new schema to let the configuration tool create them for you. Specify a database name, storage group, and buffer pool for the new schema.

    Make sure that you grant <db2_authid> the required privileges as described in Additional configuration steps for ML for z/OS Enterprise and CREATE DATABASE. If the primary authorization ID does not have sufficient privileges, consider setting the SQL authorization checking in the Current SQLID field.

  10. On the Services page,

    If you select MLz Core on the Configuration options page, you need to do the following three things: specify the port number for MLz Core services, set the password for the default user admin, and add one user as an MLz proprietary model API user. The ID for this user must be a valid RACF user ID on the system where MLz runs.

    But if you select MLz Enterprise on the Configuration options page, you need to do four things on this page: specify the port number for MLz UI, specify the port number for MLz core services, set the password for the default user admin, and add one user as an MLz System administrator. The ID for this user must be a valid RACF user ID on the system where MLz runs.

    If you plan to configure an MLz cluster, decide if you want to add this MLz instance to the cluster. If yes, specify the cluster host name or IP address. See Configuring a ML for IBM z/OS cluster for high availability for details. Also, decide if you want to enable audit trace for your MLz models.

    If you plan to enable the Dual Control feature, select the Enable Dual Control check box. When Dual Control is enabled, the system automatically enables the audit trace feature. With the System administrator’s approval, you can create, delete, and modify deployments. For more information about enabling Dual Control, see Enabling Dual Control for Machine Learning for IBM z/OS.

    Tip: If the embedded database is selected on the Metadata repository page, the Add to core services cluster toggle button will be disabled. Core service Cluster is supported only when Db2 for z/OS system is chosen as the Metadata repository.
    Tip: The availability of audit trace for model governance supports model creation and model deployment. Use the Audit trace APIs or access the UI administration dashboard - governance audit traces to check the model governance records once you enable them.
  11. On the Runtime environments page, if you select MLz Enterprise configuration, you need to specify the default runtime environment for MLz that includes both Spark and Python runtime engines, if you configure them. If you select MLz Core, you must specify the default runtime environment for MLz that includes the Spark runtime engine.

    • For Spark runtime engine, decide if you want to enable client authentication and then specify port numbers for Spark runtime engine.

    • For Python runtime engine, specify the name of Python virtual environment.

      Note:

      By default, the Python package installation source uses the IBM-hosted server. If the firewall blocks direct access to the IBM-hosted server, then you must use an internal mirror server or a proxy server to access it. To use an internal mirror server, check the user-hosted server option and provide one required parameter (the index URL), as well as two optional parameters (user ID and password).

  12. On the Model development environment page, enable Model development environment.

    To view the Model development environment page, you must select the ML for z/OS Enterprise configuration and install Python runtime engine in the Runtime environments page. It is disabled by default.

    If you enable the service then you must configure the port range for the Model development environment, including the staring port and the ending port.

  13. On the Scoring service page, specify the service name, and the port number for Python service if the MLz Enterprise configuration was selected on the Configuration options page.

    You have two options in the Scoring service configuration section: Standalone scoring service and Cluster scoring service.

    Tip: If the embedded database is selected on the Metadata repository page, or the Add to Core Services Cluster toggle button was unchecked on the Services page, Standalone scoring service will be selected automatically, and the Cluster scoring service option will be unavailable. Click the tooltip to view the helper text when Cluster scoring service is disabled. You can change the Services or Metadata repository to enable Cluster scoring service.

    If Standalone scoring service is selected, specify the port number for the scoring service, then click Next to continue to the next step.

    If Cluster scoring service is selected, all existing clusters will be shown in the following list. You can join an existing cluster or click the Create cluster button to create a new one. If you want to create a new cluster, specify the Cluster name, SD host, and SD port, then click Create to create it.

    After the instance joins a cluster, click Next to continue to the next step.

    Tip: After the cluster is created, if you want to correct the new cluster’s configuration, you can delete the cluster first, then re-create it with the correct configuration. Also make sure you follow the procedure in Configuring scoring services for high availability to configure your TCP/IP correctly for the scoring cluster to function properly.

    If errors are found during this step, correct them then click Next to continue to the next step.

  14. On the Service Hosts page, select Enable service hosts to create one or more service hosts for running the ONNX compiler and Trustworthy AI services.
    1. On the Service Hosts page, select Enable service hosts to create one or more service hosts that the ONNX compiler and Trustworthy AI services will run on.
    2. Click Add service host.
    3. Enter the required values as defined in the Create service host API .
    4. Click Create to add the service host.
    5. After you complete creating the required service hosts, click Next to continue.
  15. To enable the Trustworthy AI and ONNX compiler services, click Enable services and complete the following procedure twice, once for the Trustworthy AI service and once for the ONNX compiler service.
    1. Click Create service.
    2. Enter the service name.
    3. Select the service type.
    4. Choose a service host that you created in the previous step.
    5. Click Next.
    6. Enter the service port.
    7. Click Create.
    For more information, see Create service API.
  16. On the Review and configure page, review all your settings, correct errors, and configure MLz and services.

    The Review and configure page displays the entire configuration process. Monitor the progress and resolve errors if they occur. Do not close your browser or exit the configuration tool; wait until the configuration process completes.

    • If you select MLz Core configuration, after the configuration process completes successfully, click Exit to exit the configuration tool. It will also terminate the configuration process.
    • If you select MLz Enterprise configuration, click Exit to exit the configuration tool. It will also terminate the configuration process and launch the sign-in page of your ML for IBM z/OS web UI.
      Tip: Take note of the URL of your ML for IBM z/OS UI that consists of the host IP address and port number you entered on the Services page of the configuration tool.
      Tip: If the configuration process fails, review the $IML_HOME/iml-config/imltool_logs/tool-error.log file for details and then click Back to resolve errors. When you're ready, click Retry to continue the configuration process.