Job Scheduling

The purpose of job scheduling is to take the start data that the user has sent from the API call and merge it with a template string that is returned from the job scheduling function.  Instead of starting a session immediately, the FastX server will execute this interpolated string and any output will be returned to the user.  FastX leverages this feature to allow admins to configure FastX to execute job schedulers like SLURM, MOAB, LSF etc to start sessions.

Note that in FastX terminology, Job Scheduling and Load Balancing are two different actions.

  • Job Scheduling is the act of creating a template string in place of the start command
  • Load Balancing is the act of choosing which server to execute the start data.

When integrating LSF (or equivalent), you will execute the template function (job scheduling) on the serverId returned (load balancing).  In this instance, where the session finally gets started is up to LSF

Built In Launchers

FastX ships with several built in Job Schedulers to simplify standard load balancing algorithms

Admin > Sessions > Launcher > Launcher

  • Start Immediately — default. Start the session immediately. No scheduling.
  • Docker — launch a docker container.
  • Custom — Use a custom Job Scheduler

Custom Launchers

Admins can create custom scheduling scripts. In FastX 4, the launcher script is a custom executable script that the admin writes. Set the following environment variables in $FX_CONFIG_DIR/fastx.env

  • LAUNCHER_SCRIPT=/path/to/script — custom launcher script
  • LAUNCHER_ARGS=--arg1,--arg2,--arg3 — comma separated list of launcher arguments
  • LAUNCH_AS_CURRENT_USER=true — (optional) run the script as the FastX user. By default runs as the logged in user.

Return Code

Return status 0 will be considered successful. Any nonzero return code will be an error and will remove the session.

If you happen to have launched the session before the error, it still may appear in the list even though it gave an error.

Example Files

Python examples are available in the FastX installation /usr/lib/fastx/4/install/config/job-scheduler.d

_fastx.py

The _fastx.py library is available to users with several utility functions to simplify the boilerplate of creating a launcher

Basic Example

This example reimplements the default launch command

#!/usr/bin/python3
#Example
import json
from _fastx import get_input_from_stdin, process_output

# use the _fastx lib to get the input from stdin
myInput = get_input_from_stdin()

SYSDIR = '/usr/lib/fastx/4'

#command you will use to exec
command = myInput["defaultStartScript"]

#fallback
if len(command) == 0:
   command = SYSDIR +'/scripts/start'

args = []
args.append(command)

# send start input on stdin
args.append('--json=0')

#execute the start script
completed_process = run(args, stdout=subprocess.PIPE, input=json.dumps(myInput["start"]) stderr=subprocess.PIPE)

# process the output for FastX
process_output(completed_process)

Weblink Example

Weblinks connect to the FastX Node over the network rather than unix sockets. Special settings are needed when launching weblinks

#!/usr/bin/python3
#Example
import json
import os
from _fastx import get_input_from_stdin, process_output

# use the _fastx lib to get the input from stdin
myInput = get_input_from_stdin()

SYSDIR = '/usr/lib/fastx/4'

# the command you need to run to start the session is start-weblink
command = SYSDIR +'/scripts/start-weblink'

args = []
args.append(command)

# send start input on stdin
args.append('--json=0')

env = os.environ

# You MUST set WEBLINK_URL and WEBLINK_PRIMARY on start-weblink
weblink = my_input.get('weblink')
if(weblink is not None):
   env["WEBLINK_URL"] = weblink.get("url", "")
   env["WEBLINK_URI"] = weblink.get("uri", "/weblink")
   env["WEBLINK_PRIMARY"] = weblink.get("primary", "")

#execute the start script
completed_process = run(args, stdout=subprocess.PIPE, input=json.dumps(myInput["start"]) stderr=subprocess.PIPE)

# process the output for FastX
process_output(completed_process)

Output

Any output will be shown to the user. If the output is a JSON object with a “result” parameter, the output will be interpreted as a start success command.

Script Input

The job scheduler script will send the following input to stdin as a JSON string.

{
  "socketFile": "/path/to/fastx-server/socket",
  "rootDir": "/usr/lib/fastx/4",
  "varDir": "/var/fastx",
  "configDir": "/etc/fastx",
  "localDir": "/var/fastx/local",
  "tmpDir": "/tmp",
  "uid": 1001,
  "gid": 1001,
  "homedir": "/home/username",
  "shell": "/bin/bash",
  "login": "username",
  "defaultStartScript": "$FX_ROOT_DIR/scripts/start",
  "start": <start-object>,
  "weblink": <weblink-object>
}

start-object

This is the data collected from the user. You should pass it to the start script on stdin.
Add the command line args “–json=0” to pass start data on stdin

weblink-object

If WEBLINK_PORT is set in fastx.env or the environment the following object will be available. These options are available to the launcher script to launch weblinks

{
   "logLevel": "debug",
   "url": WEBLINK_URL,
   "uri": WEBLINK_URI,
   "primary": primary_token,
   "login": "loginname"
}

Pending Sessions

Sessions that have been scheduled but not yet connected back to the launcher are considered pending. Users cannot connect to a pending session. However there are a limited number of maintenance and information gathering actions (get info, terminate, purge) that a user can do on a pending session.