You are viewing the RapidMiner Hub documentation for version 10.3 - Check here for latest version

Real-Time Scoring Agent deployment to Web API endpoints migration

Scoring Agents serve pre-defined deployments which contain web services. The installation, update or deletion for those deployments running on a Scoring Agent have to be managed via file or REST service manually. Furthermore, Scoring Agents have no automatic load balancing. Web API Agents start exactly at this point and provide simple management of the created web services (called endpoints) as well as possible load balancing when multiple Web API Agents are up and running.

The migration of an active deployment with the underlying web services to Web API endpoints can be done in two steps:

Create a CSV file to describe the deployment to project relation.

The following example CSV list such relations for the basePaths iris and score. We assume that those are nested in the projects project-iris and project-score.
```
 basePath,  projectId    ,   baseLocation,  ref
 iris    ,  project-iris ,               ,  
 score   ,  project-score,               ,  
```
A deployment contains a config.json file with the basePath and the processLocation for each web service. If the processLocation does not start at the root level of the project, quote the prefix in the baseLocation of the CSV file. So the baseLocation combined with processLocation should represent an absolute path to the process in your project. Otherwise, let the baseLocation empty. While the basePath and related projectId have to be declared, the baseLocation and ref for the git reference have the defaults / and master.

The corresponding config.json files could look like:
```
 {
   "basePath": "iris",
   "endpoints": [
     {
       "path": "normalize",
       "processLocation": "/processes/normalize_iris",
       "parameters": [],
       "order": 0
     },
     {
       "path": "validate",
       "processLocation": "/processes/validate",
       "parameters": [],
       "order": 1
     }
   ]
 }
```
and
```
 {
   "basePath": "score",
   "endpoints": [
       {
         "path": "calculate",
         "processLocation": "/processes/calculate",
         "parameters": [],
         "order": 0
       }
   ]
 }
```
The migration process validates all the web services from the deployments and checks if those are available in the referenced projects.

Set up a Web API Agent and extend the configuration with the following environment variables because Web API Agent is distributed as a docker image:

Application	Property	Default	Description
Web API Agent	`MIGRATION_EXIT`	`false`	If the Web API Agent should shutdown after the migration
Web API Agent	`MIGRATION_WEBAPI_ENABLED`	`false`	If the migration should be executed
Web API Agent	`MIGRATION_WEBAPI_GROUP`	none	The Web API Group name, which the deployments should belong to after the migration
Web API Agent	`MIGRATION_WEBAPI_OLD_HOME_DIR`	none	Path to the home dir of the Scoring Agent, whose deployments should be migrated
Web API Agent	`MIGRATION_WEBAPI_MAPPING_FILE`	none	Path to the CSV file as description for the deployment to project relation
Web API Agent	`MIGRATION_WEBAPI_FAIL_ON_EXISTS`	`false`	If migration should fail while the deployment which should be deployed already exists
Web API Agent	`MIGRATION_WEBAPI_FAIL_ON_MAPPING_MISSING`	`false`	If migration should fail while the CSV file is missing
Web API Agent	`MIGRATION_WEBAPI_FAIL_ON_PROJECT_MISSING`	`false`	If migration should fail while a referenced project in the CSV file is missing

As the outcome for migrating the two example deployments, there would be three Web API endpoints created while they will be available under the following URLs:

https://my.aihub:port/DEFAULT/api/v1/services/iris/normalize
https://my.aihub:port/DEFAULT/api/v1/services/iris/validate
https://my.aihub:port/DEFAULT/api/v1/services/score/calculate

In the example Web API endpoint URLs, you can see that the URLs now contain a new element, in this case DEFAULT. This Web API Group name in the URL is the differentiator for the load balancer to forward requests properly to the underlying connected Web API Agents of that group. It is important to mention that any consuming applications need to adapt the former endpoint references, because the new calling URLs include the Web API Group name. For more details examine the Identify the endpoint URL.

Consider setting the MIGRATION_EXIT property to true, then just the migration step will be executed. If it's false, which is by default, then the Web API Agent will be running after the migration and those migration properties should be removed from the configuration. After the migration is complete, the old Scoring Agent can be shut down. Before removing the old Scoring Agent and the related volume with the old deployments, you should make sure that all necessary services are now listed in RapidMiner AI Hub endpoints section.

Categories

Versions

Real-Time Scoring Agent deployment to Web API endpoints migration