Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


Harris Geospatial / Docs Center / Geospatial Services Framework / GSF Tutorial: Custom Licensing

Geospatial Services Framework

GSF Tutorial: Custom Licensing

GSF - Tutorial - Custom Licensing

This tutorial shows how to setup GSF if your underlying services require specific types of licenses to be available. For example, to have GSF run ENVI or IDL tasks you need to obtain the ENVI or IDL Service Engine licenses respectively.

In addition to ENVI and IDL Service Engines requiring a specific type of license when running, the license entitlements grant a maximum number of concurrent processes that can use that entitlement at any given time. Each job needs to have the correct entitlements to perform the required processing. For example when obtaining an ENVI Service Engine entitlement you are given a certain number of licenses that your machine is allowed to acquire. If this number is four then you can run four ENVI tasks at a time on one machine.

This licensing model coincides with the GSF worker option. The worker option specifies the number of concurrent jobs each machine can run, essentially defining the size of your local cluster. Ideally you want to match the number of workers to the number of ENVI Service Engine licenses you have for one machine instance. If you have configured the server with more workers than licenses, jobs will start to fail with error messages reporting that the task engine was unable to acquire a license.

It is also possible to have Engines that have differing numbers of entitlements. Since ENVI Services Engine and IDL Service Engine require separate licenses, you may end up with four IDL Service Engine licenses and only one ENVI Service Engine license. With the default configuration you might have all the workers try to process ENVI jobs concurrently and the jobs will fail due to licensing. The best solution to this problem is routing. However, it doesn't always make sense to run a cluster to handle a licensing issue. In GSF, it is possible to route jobs to specific workers without running a cluster. This tutorial will show you how to configure workers with specific routes and how to automatically route jobs to those workers. One worker can be assigned all ENVI jobs so that the number of licenses matches the number of workers. This would free up the additional workers to handle other jobs that don't have the same license limits.

Note: This tutorial uses routing to handle custom licensing. It is recommended to follow the custom-route-mapper tutorial before this one.

The WorkerConfig Option


WorkerConfig is a top-level config option allowing you to provide customization for each worker on your node. With this option you can assign each worker with a new list of routes, overriding the default routes in the top-level config. If you have four workers on your node, you can set all four workers to unique routes.

  "workerConfig": [
    {"routes": ["worker1route"]},
    {"routes": ["worker2route"]},
    {"routes": ["worker3route"]},
    {"routes": ["worker4route"]}
  ],
  ...

In this tutorial, you will use this option to sync the number of workers to your license model.

Create A Custom Licensing Configuration


In this example you will configure the server to handle the scenario where you have purchased four IDL Service Engine entitlements and one ENVI Service Engine entitlement.

Ideally, there should be four workers available to pick up IDL jobs and one worker available to pick up ENVI jobs. If you configured the server with four workers, ENVI jobs could fail since only one license is available to perform ENVI work. Configuring individual workers to perform only specific types of jobs prevents job failure due to licensing entitlements. Jobs will remain on the job queue until a worker with an available entitlement becomes available.

Updating Number of Workers

To have four workers available to pick up IDL jobs and one worker available for ENVI jobs, update the server's configuration to have five workers. You can update the configuration using the command line utility updateConfig.js. This utility will also backup the config.json file so you can go back to the previous server configuration after completing this tutorial.

Start a command prompt in the GSFxx directory and execute the following command:

node updateConfig.js config.json --set workers=5

Alternatively, you may also manually edit the config.json file. Below is an example of the config.json:

  "workers": 5

Define the Worker Routes

To specify that only one of the workers should pick up jobs on an ENVI route, update the server configuration file to add the following:

  "workerConfig": [
    {"routes": ["ENVI"]}
  ],

Restart the server for the updated configuration to take effect.

Add the Service Route Mapper

Now that the workerConfig option has been updated to have one worker picking up jobs on an ENVI route, you need to have a route mapper that can identify ENVI jobs and direct them to the ENVI route. In this case you can use the gsf-service-route-mapper shipped with GSF that maps all jobs submitted on specific service(s) to a specific route. Copy the following into the config.json to enable the gsf-service-route-mapper to put jobs submitted to the ENVI service into the ENVI route.

  "routeMappers": [
    {
      "type": "gsf-service-route-mapper",
      "serviceRoutes": [
        {
          "services": ["ENVI"],
          "route": "ENVI"
        }
      ]
    }
  ],
  ...

Restart the server for the updated configuration to take effect. You can now submit multiple ENVI jobs simultaneously and all ENVI jobs will be placed on the ENVI route to be picked up by the worker configured for the ENVI route.

With this configuration, IDL jobs are still using the default route the other 4 workers will process those jobs. The worker with the overridden route will no longer process jobs on the default route and will only handle ENVI jobs.

Other Licensing Scenarios


Besides the number of service engine licenses you may acquire, there are other licensing scenarios you may encounter.

Feature Licenses

Sometimes you can have entitlements for specific ENVI features. These entitlements grant you permissions to run a few specific ENVI tasks you do not have access to with the ENVI Service Engine license. If you have fewer feature entitlements than ENVI Task Engine licenses, you will want to route jobs that use that feature to a new route.

For example if you have two licenses to run a specific task, create a new route for the task and update the workerConfig option so only two workers can run the job.

  "workerConfig": [
    {"routes": ["featureRoute"]},
    {"routes": ["featureRoute"]}
  ],

To route the tasks to the specified route, follow the instructions on creating a custom-route-mapper and add the custom-route-mapper to the top-level config being sure to list out the relevant tasks.

  "routeMappers": [
    {
      "type": "./custom-route-mapper",
      "taskRoutes": [
        {
          "tasks": ["featureTask"],
          "route": "featureRoute"
        }
      ]
    }
  ],
  ...

Once the route mapper is added, restart the service so each worker can restart with a new list of routes. Your featureTask will now only run on the first two workers.



© 2017 Exelis Visual Information Solutions, Inc. |  Legal
My Account    |    Buy    |    Contact Us