SM-ML Settings

Overview

This article describes how to install and configure the SM-ML service (sm-ml-service), connect it to Search Anywhere Framework, and prepare Docker and Kubernetes runtime environments.

SM-ML is the backend service for ML Studio. It receives requests to train and apply models and deploys compute containers in Docker or Kubernetes. The service is installed separately on a dedicated server.

Before installation, prepare the server according to the selected runtime environment:

• Docker - a dedicated server with Docker installed. To run computations on a GPU, install a GPU and configure access to it from containers
• Kubernetes - a Linux server with access to the cluster API. Computations will run on cluster nodes

The distribution includes the following files:

• sm-ml-service - the service executable (Linux)
• sm-ml-runtime-6.1.0-amd64.tar - the runtime image archive (amd64)

info

The examples use release version 6.1.0. When running the commands, specify the version included in your distribution.

Installing the Service (Linux, systemd)

To install sm-ml-service as a systemd service, run the following commands on the server:

# 1. Create a system user in the docker group (run once)
sudo useradd -r -s /sbin/nologin -G docker smml

# 2. Install the service as the sm-ml.service systemd service
sudo ./sm-ml-service install --user smml \
    --docker-sock /var/run/docker.sock --enable

# 3. Start the service and verify that it is running
sudo systemctl start sm-ml.service
curl http://localhost:18089/health

To view the complete list of installation parameters, run the following command:

./sm-ml-service install --help

By default, the service uses the current directory as its working directory. Data is stored in the data/ subdirectory.

Configuration File

Service parameters can be specified in a YAML configuration file. If the configuration file is missing, the service uses the default values.

By default, the service loads the config.yaml file located next to the executable. To specify a different path, use the --config <path> parameter or the SM_ML_CONFIG environment variable.

To create a configuration file, go to the directory containing the service executable and create the config.yaml file:

cat > config.yaml <<'EOF'
server:
  port: 18089
  ssl:
    enabled: false               # enable HTTPS
    certificate: ""              # path to the certificate (PEM)
    certificate-private-key: ""  # path to the private key (PEM)
logging:
  file:
    path: logs                   # directory for log files
smartmonitor:
  url: ""                        # Search Anywhere Framework address
  insecure-skip-verify: false    # do not verify the Search Anywhere Framework TLS certificate
  ca-cert-path: ""               # trusted CA certificate (PEM)
EOF

The following parameters are available in the configuration file:

Parameter	Description	Default
server.port	Incoming connection port	18089
server.ssl.enabled	Enables HTTPS	false
server.ssl.certificate	Path to the certificate (PEM)	-
server.ssl.certificate-private-key	Path to the private key (PEM)	-
logging.file.path	Directory for the sm-ml-service.log (general) and request-headers.log (requests and their headers) log files	logs
smartmonitor.url	Search Anywhere Framework server address	-
smartmonitor.insecure-skip-verify	Disables verification of the Search Anywhere Framework TLS certificate	false
smartmonitor.ca-cert-path	Path to a trusted CA certificate (PEM)	-

If server.ssl.enabled is set to true, the service accepts HTTPS connections. If the certificate and private key are not specified, the service generates a self-signed certificate in memory at startup.

To verify that the service works with a self-signed certificate, run the following command:

curl -k https://localhost:18089/health

Issuing a Service Certificate

To configure HTTPS, it is recommended to issue a service certificate and sign it with your own certificate authority (CA) certificate (typically the ca-cert.pem and ca-key.pem files).

Add the CA certificate (ca-cert.pem) to the truststore once. You can then reissue the server certificate without updating the truststore.

The examples use the host name sm-ml.example.com and port 30000. Replace them with values appropriate for your environment when running the commands.

1. Creating a Private Key and CSR

Create a private key and certificate signing request (CSR) on the service host:

openssl ecparam -genkey -name prime256v1 -out server.key
chmod 600 server.key
openssl req -new -key server.key -out server.csr -subj "/CN=sm-ml.example.com"

The server.key file contains the private key and must be stored only on the service host.

2. Configuring the Subject Alternative Name

Create a certificate extension file and specify the host name that clients will use to access the service in the Subject Alternative Name field:

cat > server.ext <<'EOF'
subjectAltName = DNS:sm-ml.example.com
extendedKeyUsage = serverAuth
EOF

Important

Java validates the host name against the subjectAltName value. The Common Name value is not considered during this validation.

3. Signing the CSR

Sign the CSR with the CA certificate and private key:

openssl x509 -req -in server.csr \
  -CA ca-cert.pem -CAkey ca-key.pem -CAcreateserial \
  -days 825 -out server.crt \
  -extfile server.ext

If the ca-key.pem file is password-protected, OpenSSL prompts for the password while running the command. In this example, the certificate is issued for 825 days, which is the maximum validity period accepted by modern clients.

To verify the issued certificate, run the following command:

openssl verify -CAfile ca-cert.pem server.crt

4. Configuring HTTPS

Enable HTTPS in config.yaml and specify the paths to the certificate and private key:

server:
  port: 30000
  ssl:
    enabled: true
    certificate: "server.crt"
    certificate-private-key: "server.key"

To apply the changes, restart the service and verify that it is accessible over HTTPS:

sudo systemctl restart sm-ml.service
curl --cacert ca-cert.pem https://sm-ml.example.com:30000/health

5. Configuring the Java Truststore

On the client host, import the CA certificate into the Java truststore:

keytool -importcert -alias example-ca \
  -file ca-cert.pem \
  -keystore truststore.jks \
  -storepass changeit -noprompt

Important

Import the CA certificate into the truststore, not the server certificate.

To run a Java client with the created truststore, specify the following parameters:

-Djavax.net.ssl.trustStore=/path/to/truststore.jks
-Djavax.net.ssl.trustStorePassword=changeit

To make all Java applications on the host trust the CA certificate, import it into the shared JDK cacerts store instead of a separate truststore:

keytool -importcert -alias example-ca \
  -file ca-cert.pem \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit -noprompt

The examples use the standard cacerts store password: changeit.

Important

The client must access the service using the name specified in subjectAltName (https://sm-ml.example.com:30000). Accessing the service by IP address causes a validation error unless the address was added to subjectAltName when the certificate was issued (for example, subjectAltName = DNS:sm-ml.example.com, IP:10.0.0.5).

Configuring API Access Verification

To enable API access verification through Search Anywhere Framework, specify the Search Anywhere Framework address in the smartmonitor.url parameter.

When the service receives an incoming request, it forwards the request headers in a GET <smartmonitor.url>/_core/system/access request. Search Anywhere Framework verifies the user's permissions and returns the result:

• access is allowed for a 2xx status code
• the request is rejected for any other status code
• access is denied if Search Anywhere Framework is unavailable

The /health and OPTIONS requests are processed without verification. To disable access verification completely, leave smartmonitor.url empty.

If Search Anywhere Framework uses a certificate issued by a private certificate authority, specify the path to the CA certificate in smartmonitor.ca-cert-path.

Important

Setting smartmonitor.insecure-skip-verify: true disables verification of the Search Anywhere Framework TLS certificate. Using this parameter reduces connection security.

After changing the configuration, restart the service:

sudo systemctl restart sm-ml.service

Configuring Search Anywhere Framework

To connect Search Anywhere Framework to sm-ml-service, configure the cluster settings and save the user's password. Run all requests in this section in the Developer Console (Main Menu - System Settings - Developer Console).

1. Configuring the Service Connection

Specify the service address, port, and connection parameters:

PUT _cluster/settings
{
  "persistent": {
    "sme.ml.service_url": "https://sm-ml.example.com/",
    "sme.ml.service_port": 30000,
    "sme.ml.timeout": 300000,
    "sme.ml.enabled": true,
    "sme.ml.user": "sm_ml_user"
  }
}

Setting	Description
sme.ml.service_url	Service address (using the name from the certificate's subjectAltName)
sme.ml.service_port	Service port
sme.ml.timeout	Service request timeout, ms
sme.ml.enabled	Enables integration with the service
sme.ml.user	Name of the user on whose behalf requests are made

2. Saving the User Password

Save the password of the user specified in sme.ml.user to the Search Anywhere Framework keystore:

POST /_core/keystore/sm.core.ml.password
{
  "value": "<password>"
}

info

After applying the settings, the train and predict SAFL commands are executed through sm-ml-service. For a usage example, see the ML Studio Step-by-Step Guide.

Docker Runtime Environment: Loading the Image

Load the runtime image into Docker on the host where the compute containers will run.

Run the following command to load the image:

docker load -i sm-ml-runtime-6.1.0-amd64.tar

To verify that the image has been loaded, run the following command:

docker images sm-ml-runtime

Kubernetes Runtime Environment

To connect a Kubernetes environment, prepare the target cluster's kubeconfig file. The file must be accessible on the host where sm-ml-service is installed.

1. Connecting to the Cluster

Install kubectl on the host running sm-ml-service. Then place the cluster's kubeconfig file in ~/.kube/config, or specify its path in the KUBECONFIG environment variable.

The kubeconfig file is usually copied from the cluster's control plane node:

mkdir -p ~/.kube
scp <control-plane-node>:/etc/kubernetes/admin.conf ~/.kube/config

To verify the cluster connection, run the following commands:

kubectl cluster-info
kubectl get nodes

2. Exporting the Configuration

Export the active kubeconfig configuration with embedded certificates to a separate file:

kubectl config view --raw --minify > kubeconfig.yaml

This command uses the following parameters:

• --raw - includes certificates and keys in the configuration
• --minify - includes only the current context

3. Creating an Environment

Go to Main Menu - System Settings - Module Settings - ML STUDIO - Machine Learning Environments, and click Create.

In the Connection Type field, select kubernetes, and then complete the following fields:

• Kubeconfig YAML - the contents of the kubeconfig.yaml file
• Node URL - the external address of the node or ingress, for example, http://<node-host>. Links to deployment services (API and Jupyter) are generated based on this address

Click Save. The created environment appears in the Environment field of the Create Deployment form.

To create an environment through the service API, run the following request:

curl -X POST http://localhost:18089/__ui/environments \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<environment-name>",
    "connector": "kubernetes",
    "kubeconfig": "<complete kubeconfig YAML>",
    "node_port_url": "http://<node-host>"
  }'