Configure Machine Learning Server 9.2.1 to operationalize analytics (Enterprise)

  • Article

Important

This content is being retired and may not be updated in the future. The support for Machine Learning Server will end on July 1, 2022. For more information, see What's happening to Machine Learning Server?

Applies to: Machine Learning Server 9.2.1                        (See instructions for latest release.)

You can configure Microsoft Learning Server after installation to act as a deployment server and to host analytic web services for operationalization. Machine Learning Server offers two types of configuration for operationalizing analytics and remote execution: One-box and Enterprise. This article describes the enterprise configuration. For more on one-box configurations, see here.

An enterprise configuration involves multiple web and compute nodes that are configured on multiple machines along with other enterprise features. These nodes can be scaled independently. Scaling out web nodes enables an active-active configuration that allows you to load balance the incoming API requests. Additionally, with multiple web nodes, you must use a SQL Server or PostgreSQL database to share data and web services across web node services. The web nodes are stateless therefore there is no need for session stickiness if you use a load balancer.

For added security, you can configure SSL and authenticate against Active Directory (LDAP) or Azure Active Directory in this configuration.

Configure Machine Learning Server on enterprise architecture

How to configure

Important

For a speedy setup in Azure, try one of our Azure Resource Manager templates stored in GitHub. This blog post explains how.

1. Configure a database

While the web node configuration sets up a local SQLite database by default, you must use a SQL Server or PostgreSQL database for this configuration for any of the following situations:

  • Have multiple web nodes (so data can be shared across web nodes)

  • Want to achieve higher availability

  • Need a remote database for your web node

To configure that database, follow these instructions.

Warning

Choose and configure your database now. If you configure a different database later, all data in your current database is lost.

2. Configure compute nodes

Configure one or more compute nodes as needed. We highly recommend that you configure each node (compute or web) on its own machine for higher availability.

Note

In the Enterprise configuration, side-by-side installations of a web and compute node are not supported.

  1. Install Machine Learning Server and its dependencies as follows. Learn about supported platforms for this configuration.

    • Windows instructions: Installation steps | Offline steps

      For SQL Server Machine Learning Services, you must also manually install .NET Core 1.1 and add a registry key called 'H_KEY_LOCAL_MACHINE\SOFTWARE\R Server\Path' with a value of the parent path to the R_SERVER or PYTHON_SERVER folder (for example, C:\Program Files\Microsoft SQL Server\140).

    • Linux instructions: Installation steps | Offline steps

  2. Launch the administration utility with administrator privileges.

  3. From the main utility menu, choose Configure server and then choose Configure a compute node from the submenu.

  4. If you plan on configuring SSL/TLS and install the necessary certificates on the compute node, do so now.

  5. Open the port 12805 on every compute node. If you plan to configure SSL/TLS, you must do so BEFORE opening this port.

    • On Windows: Add a firewall exception to open the port number.

    • On Linux: Use 'iptables' or the equivalent command to open the port number.

You can now repeat these steps for each compute node you want to add.

3. Configure web nodes

In an enterprise configuration, you can set up one or more web nodes. It is possible to run the web node service from within IIS.

  1. Install Machine Learning Server and its dependencies as follows. Learn about supported platforms for this configuration.

    • Windows instructions: Installation steps | Offline steps

      For SQL Server Machine Learning Services, you must also manually install .NET Core 1.1 and add a registry key called 'H_KEY_LOCAL_MACHINE\SOFTWARE\R Server\Path' with a value of the parent path to the R_SERVER or PYTHON_SERVER folder (for example, C:\Program Files\Microsoft SQL Server\140).

    • Linux instructions: Installation steps | Offline steps

  2. Launch the administration utility with administrator privileges to configure a web node:

    Note

    Bypass these interactive steps to install the node and set an admin password using these command-line switches: -silentwebnodeinstall mypassword uri1,uri2 Learn more about command-line switches for this utility here.

    1. From the main menu, choose Configure server. Then, choose Configure a web node from the submenu.

    2. When prompted, provide a password for the built-in, local operationalization administrator account called 'admin'. Later, you can configure the server to authenticate against Active Directory (LDAP) or Azure Active Directory.

    3. When prompted, enter the IP address of each compute node you configured. You can specify a specific URI or specify IP ranges. For multiple compute nodes, separate each URI with a comma.

      For example: http://1.1.1.1:12805, http://1.0.1-3.1-2:12805

      In this example, the range represents six IP values: 1.0.1.1, 1.0.1.2, 1.0.2.1, 1.0.2.2, 1.0.3.1, 1.0.3.2.

    4. Return the main menu of the utility.

    Important

    When configuring your web node, you might see the following message: "Web Node was not able to start because it is not configured." Typically, this is not really an issue since the web node is automatically restarted within 5 minutes by an auto-recovery mechanism.

  3. In the same utility, test the configuration. From the main utility menu, choose Run Diagnostic Tests and choose a diagnostic test.

  4. Exit the utility.

  5. If you plan on configuring SSL/TLS and install the necessary certificates on the compute node, do so now.

  6. Open the port 12800 on every web node. If you plan to configure SSL/TLS, you must do so BEFORE opening this port.

    • On Windows: Add a firewall exception to open the port number.

    • On Linux: Use 'iptables' or the equivalent command to open the port number.

You can now repeat these steps for each web node you want to add.

Important

Machine Learning Server uses Kestrel as the web server for its operationalization web nodes. Therefore, if you expose your application to the Internet, we recommend that you review the guidelines for Kestrel regarding reverse proxy setup.

4. Setup enterprise-grade security

In production environments, we strongly recommend the following approaches:

  1. Configure SSL/TLS and install the necessary certificates.

  2. Authenticate against Active Directory (LDAP) or Azure Active Directory.

  3. For added security, restrict the list of IPs that can access the machine hosting the compute node.

Important! For proper access token signing and verification across your configuration, ensure that the JWT certificate settings are exactly the same for every web node. These JWT settings are defined on each web node in the configuration file, appsetting.json. Learn more...

5. Provision on the cloud

If you are provisioning on a cloud service, then you must also create inbound security rule for port 12800 in Azure or open the port through the AWS console. This endpoint allows clients to communicate with the Machine Learning Server's operationalization server.

6. Set up a load balancer

You can set up the load balancer of your choosing. Keep in mind that web nodes are stateless. Therefore, session persistence ("stickiness") is NOT required.

7. Post configuration steps

  1. Update service ports, if needed.

  2. Run diagnostic tests.

  3. Evaluate the configuration's capacity.

How to upgrade

To replace an older version, you can uninstall the older distribution before installing the new version (there is no in-place upgrade).

Carefully review the steps in the following sections.

Upgrade a compute node

Important

Before you begin, back up the appsettings.json file on each node in case of an issue during the upgrade process.

  1. Uninstall Microsoft R Server 9.0 or 9.1 using the instructions in the article Uninstall Microsoft R Server to upgrade to a newer version. The uninstall process stashes away a copy of your 9.0 or 9.1 configuration files under this directory so you can seamlessly upgrade to Machine Learning Server 9.2.1 in the next step:

    • Windows: C:\Users\Default\AppData\Local\DeployR\current

    • Linux: /etc/deployr/current

  2. Install Machine Learning Server and its dependencies as follows. Learn about supported platforms for this configuration.

    • Windows instructions: Installation steps | Offline steps

      For SQL Server Machine Learning Services, you must also manually install .NET Core 1.1 and add a registry key called 'H_KEY_LOCAL_MACHINE\SOFTWARE\R Server\Path' with a value of the parent path to the R_SERVER or PYTHON_SERVER folder (for example, C:\Program Files\Microsoft SQL Server\140).

    • Linux instructions: Installation steps | Offline steps

  3. Launch the administration utility with administrator/root/sudo privileges. The utility checks to see if any configuration files from past releases are present under the current folder mentioned previously.

  4. Choose Configure server from the menu and then Configure a compute node from the submenu.

  5. When the script asks you if you want to upgrade, enter y. The node is automatically set up using the configuration you had for R Server 9.0 or 9.1.

You can now repeat these steps for each compute node.

Upgrade a web node

Important

Before you begin, back up the appsettings.json file on each node in case of an issue during the upgrade process.

  1. Uninstall Microsoft R Server 9.0 or 9.1 using the instructions in the article Uninstall Microsoft R Server to upgrade to a newer version. The uninstall process stashes away a copy of your 9.0 or 9.1 configuration files under this directory so you can seamlessly upgrade to Machine Learning Server 9.2.1 in the next step:

    • Windows: C:\Users\Default\AppData\Local\DeployR\current

    • Linux: /etc/deployr/current

  2. Install Machine Learning Server and its dependencies as follows. Learn about supported platforms for this configuration.

    • Windows instructions: Installation steps | Offline steps

      For SQL Server Machine Learning Services, you must also manually install .NET Core 1.1 and add a registry key called 'H_KEY_LOCAL_MACHINE\SOFTWARE\R Server\Path' with a value of the parent path to the R_SERVER or PYTHON_SERVER folder (for example, C:\Program Files\Microsoft SQL Server\140).

    • Linux instructions: Installation steps | Offline steps

  3. Launch the administration utility with administrator/root/sudo privileges. The utility checks to see if any configuration files from past releases are present under the current folder mentioned previously.

  4. Choose Configure server from the menu and then Configure a web node from the submenu.

  5. When the script asks you if you'd like to upgrade, enter y. The node is automatically set up using the configuration you had for R Server 9.0 or 9.1.

  6. From the main menu, choose the option to Run Diagnostic Tests to test the configuration.

You can now repeat these steps for each node.