Introduction:

Use case: 

As clusters get larger and workloads vary it is becoming critical that the jobs get evaluated in as short as time possible to ensure that the correct workload is being run. Using multiple schedulers to address this issue can allow for different scheduling policies and quicker turnaround time for large number of jobs or nodes.

Gist of design proposal::

PBS scheduler in it's current form can run easily run in multiple instances on the same machine. There are only two major problems that we have to deal with:

• Managing the scheduler - This includes starting the scheduler, configuring them, making PBS server connect to each one of them and then make them run on specific events.
• Make sure that schedulers do not overrun on each other's territory. Make sure that they run on clearly partitioned complex in terms of jobs and nodes.

Design proposal mentioned below tends to address both these problem.

Forum discussion

• Interface 1: Extend PBS to support a list of scheduler objects

  • Visibility: Public
  • Change Control: Stable
  • Details:
    • PBS supports a list of scheduler objects to be created using qmgr. It is similar to how we create nodes in server.
    • qmgr command can be used to create a scheduler object . It must be invoked by a PBS admin/manager.
    • To create a scheduler object and make it run, the following are the attributes that can be set by the user
      • Name of the scheduler is mandatory to be given while creating a scheduler object. 
        • qmgr -c "c sched multi_sched_1"
          • This will create/set the following attributes for the sched object
            
            • sched_port - port number on which multi_sched_1 is going to run. This is mandatory parameter and should be given before start of this scheduler.
            • sched_host - host name on which multi_sched_1 is going to run. This is mandatory parameter and should be given before start of this scheduler.
            • partition = "None" (default)*
              
            • sched_priv = $PBS_HOME/sched_priv_multi_sched_1 (default)*
              
            • sched_log = $PBS_HOME/sched_log_multi_sched_1 (default)*
              
            • scheduling = False (default)*
            • scheduler_iteration = 600 (default)*
              
            • comment 
              

              • sites can use the comment field to

              • notify them if scheduler undergoes restarting 2-3 times due to potential crashes in an hour for example (i.e. comment => “NEEDS_ATTENTION”)

              • tell when a particular scheduler is ready to function again by setting the comment as follows.

                • comment => “READY_TO_USE

• • • • "*" indicates that the value will be visible when the admin lists or prints the sched object after the sched object is create

• Set the priv directory for the scheduler.
  • The directory should have permissions set as "750". By default a sched object has it's priv directory set as $PBS_HOME/sched_priv_<sched-name>. If the directory is already used by some other scheduler then error code is set "15216" with error message 
    "Another scheduler has same value for its sched_priv directory"
  • qmgr -c "s sched multi_sched_1 sched_priv=/var/spool/pbs/sched_priv_1"
  • If the priv directory is not accessible by scheduler process, or the scheduler files are not found in the directory, then comment is updated with following error message
    "PBS failed validation checks for sched_priv directory"
  Set the log directory for the scheduler. 
  • The directory should have permissions as "755". By default a sched object has it's logs directory set as $PBS_HOME/sched_log_<sched_name>. . If the directory is already used by some other scheduler then error code is set "15215"  with error message
    "Another scheduler has same value for its sched_log directory"
  • qmgr -c "s sched multi_sched_1 sched_log=/var/spool/pbs/sched_log"
  • If the log directory is not accessible by scheduler process, or the scheduler files are not found in the directory, then comment is updated with following error message
    "Unable to change the sched_log directory"
  • By default a multi-sched object has scheduling set as False.
    qmgr -c " s sched <scheduler name> scheduling = 1"
• The following attributes will be set on the default scheduler if the the user sets them on the server
  • scheduling
  • scheduling_iteration
• Max length of scheduler name is 15
• By default PBS server will configure a default scheduler which will run out of the box.
  
  • • The name of this default scheduler will be "default"
    • The sched_priv directory of this default scheduler will be set to the $PBS_HOME/sched_priv
    • Default scheduler will log in $PBS_HOME/sched_log directory.
    • Default scheduler will be provided with default set of policies as mentioned in sched_config.
    • One can set a scheduler attribute through qmgr either in the usual way as shown below or they can use the new syntax. Old syntax is supported for backward compatibility which will be deprecated soon.
      Ex:  qmgr -c "set sched job_sort_formula_threshold = <value>
             qmgr -c "set sched default job_sort_formula_threshold = <value>"

Interface 2: Changes to PBS scheduler

• Visibility: Public
• Change Control: Stable
• Details:
  • Scheduler now has additional attributes which can be set in order to run it.
    • sched_priv - to point to the directory where scheduler keeps the fairshare usage, resource_group, holidays file and sched_config
    • sched_log - to point to the directory where scheduler logs.
    • partition - name of the partition for which this scheduler is going to schedule jobs.
    • sched_host - hostname on which scheduler is running. For default scheduler it is set to pbs server hostname.
    • sched_port - port number on which scheduler is listening.
    • state - This attribute shows the status of the scheduler. It is a parameter that is set only by pbs server.
  • One can assign only one partition per scheduler object. Once set, given scheduler object will only schedule jobs from the queues attached to specified partition"
    • qmgr -c "s sched multi_sched_1 partition='part1'"
  • If no partition is specified for a given scheduler object, other than the default scheduler where no partition value can be set, then that scheduler will not schedule any jobs.
  • By default, All new queues created will be scheduled by the default scheduler, until they have been assigned to a specific partition.
  • A partition once attached to a scheduler can not be attached to a second scheduler without removing it from the first scheduler. If tried, then it will throw following error:
    • qmgr -c "s sched multi_sched_1 partition='part2'"
      Partition part2 is already associated with scheduler <scheduler name>.
  • Scheduler object "state" attribute will show one of these 3 values  - down, idle, scheduling 
    • If a scheduler object is created but scheduler is not running for some reason state will be shown as "down"
    • If a scheduler is up and running but waiting for a cycle to be triggered the state will be shown as "idle"
    • If a scheduler is up and running and also running a scheduling cycle then the state will be shown as "scheduling "
    • Default scheduler's state is by default "idle" since the "scheduling" of server is set to true with default installation. 
•  
  • The default sched object is the only sched object that cannot be deleted.
  • Trying to set sched_port, sched_priv and sched_host on default scheduler will not be allowed. The following error message is thrown in server_logs when we try to change sched_priv directory.
    • qmgr -c "s sched default sched_priv = /tmp
      Operation is not permitted on default scheduler
  • Trying to start a new scheduler other than the default scheduler, without assigning a partition will throw the following error message in scheduler logs.
             Scheduler does not contain a partition

  • If Scheduler fails to accept new value for its sched_log directory then comment of the corresponding scheduler object at server is updated with the following message.  Also, the scheduling attribute is set to false.
            Unable to change the sched_log directory

  • If Scheduler fails to accept new value for its sched_priv directory then comment of the corresponding scheduler object at server is updated with the following message.  Also, the scheduling attribute is set to false.
           Unable to change the sched_priv directory

  • If PBS validation checks for new value of sched_priv directory do not pass then comment of the corresponding scheduler object at server is updated with the following message. Also, the scheduling attribute is set to false.
          PBS failed validation checks for sched_priv directory
  • If Scheduler is successful in accepting the new log_dir configured at qmgr then the following error message is thrown in the scheduler logs.

           Scheduler log directory is changed to <value of path of the log directory>

  • If Scheduler is successful in accepting the new sched_priv configured at qmgr then the following error message is thrown in the scheduler logs.
           Scheduler priv directory is changed to <value of path of the sched_priv directory> 

  • If an admin unset partition from a scheduler then this scheduler is identical to default scheduler in which case PBS scheduler will shutdown itself and following error message is logged in scheduler logs.
           Scheduler does not contain a partition.   

  • If Scheduler fails in getting its stats from Server then the following error message is shown in scheduler logs.
           Unable to retrieve the scheduler attributes from server     

  • A new option -I is introduced to provide a name to a scheduler. If we run pbs_sched without this option then it is considered as default scheduler whose name is "default".
           Example: pbs_sched -I sc1 -S 15051
           Here scheduler is started on port number 15051 whose id/name is "sc1".

                                                                                                                                                                                                                                

    
    

Interface 3: Removed

Interface 4: Changes to PBS server.

• Visibility: Public
  Change Control: StableDetails:
  • PBS does not allow attributes like scheduling, scheduler_iteration to be set on PBS server object.
  • scheduling and scheduler_iteration now belong to the sched object
    • During failover when secondary server takes control it will try to connect to connect to schedulers by using their sched_host attribute.
      
      • If secondary server is unable to connect to scheduler running on remote host then it will start that scheduler locally and update it's "sched_host" attribute.
      • When Primary pbs server takes control from secondary it will always check if scheduler's sched_host attribute matches it's server name, if it doesn't then it will shutdown the remote scheduler and spawn it locally on primary server.
    • If set at the server level, the changes will be applied to the default sched object
  • As backward compatibility PBS still allows attributes like scheduling, scheduler_iteration to be set on PBS server object. Any changes made to these attributes are automatically reflected in default scheduler. Similarly if any changes are made to these attributes in default scheduler, they are automatically reflected in the server object.
  • If at any point in time if Server is not able to contact or reach the corresponding scheduler one of the following messages are shown in server_logs.
           Unable to reach scheduler associated with partition [<partition id>]
           Unable to reach scheduler associated with job <job id>

Interface 5: Changes to PBS Nodes objects.

• Visibility: Public
• Change Control: Stable
• Details:
  • Node object in PBS will have an additional attribute called "partition" which can be used to associate a node to a particular partition.
    • This attribute will be of type string and it will be settable only by Manager/operator and viewable by all users.
  • If "partition" attribute is not set, node will not belong to any partition and default scheduler will schedule jobs on this node.
  • PBS admin/manager can set node's partition attribute to an existing partition name and it's corresponding scheduler will be scheduling jobs on this node.
  • If nodes are associated to a partition then they can not be linked to any queue which isn't part of that partition. Trying to set a node to a queue which isn't part of it's partition will result into the following error:
    • Qmgr: s n node1 queue=workq1
      qmgr obj=stblr3 svr=default: Partition p1 is not part of queue for node
      qmgr: Error (15220) returned from server
  • If a node is associated to a queue then trying to set a partition on this node which does not belong to the same queue will result into the following error.
    • Qmgr: s n stblr3 partition=p2
      qmgr obj=stblr3 svr=default: Queue q1 is not part of partition for node
      qmgr: Error (15219) returned from server
  • If a queue is associated to one or multiple nodes then trying to change partition of this queue to a value other than those that are set on these nodes will result into the following error.
    • Qmgr: s q q1 partition=p2
      qmgr obj=q1 svr=default: Invalid partition in queue
      qmgr: Error (15221) returned from server

  • Nodes with a partition ID (but no queue statement) can run jobs from any of the queues assigned to the same partition (depending upon resource constraints).

Interface 6: Changes to Queues.

• Visibility: Public
• Change Control: Stable
• Details:
  
  • Queue will have a new queue attribute named "partition" which can be used to associate a queue to a particular partition.
    • This attribute will be of type string and it will be settable only by admin/manager and viewable by all users.
    • If "partition" attribute is not set to anything, queue will not belong to any partition and the default scheduler will schedule jobs from this queue.
    • Setting "partition" attribute on routing queues is not allowed. Trying to set the same will throw the following error.

    • Qmgr: s q q4 partition=p1
      qmgr obj=q4 svr=default: Cannot assign a partition to route queue
      qmgr: Error (15217) returned from server

    • Execution queue can not be changed to routing queue if "partition" attribute is set on it. Trying to set it will throw the following error.
      Qmgr: s q q1 queue_type=route
      qmgr obj=q1 svr=default: Route queues are incompatible with the partition attribute queue_type
      qmgr: Error (15218) returned from server

      
      
      

Interface 7: How PBS server runs scheduler.

• Visibility: Public
• Change Control: Stable
• Details:
  • Upon startup PBS server will start all schedulers which have their scheduling attribute set to "True"
    • "PBS_START_SCHED" pbs.conf variable is now deprecated and it's value will get overridden by schedulers "scheduling" attribute.
  • PBS server will connect to these schedulers on their respective host names and port number.
  • Scheduling cycles for all configured schedulers are started by PBS server when a job is queued, finished, when scheduling attribute is set to True or when scheduler_iteration is elapsed.
    • When a job gets queued or finished, server will check it's corresponding queue and try to connect to it's corresponding scheduler to run a scheduling cycle.
    • If a scheduler is already running a scheduling cycle while server will just wait for the previous cycle to finish before trying to start another one.
    • If job_accumulation_time is set then server will wait until that time has passed after the submission of a job before starting a new cycle.
  • Each scheduler queries whole universe of all schedulers, server, queues, nodes information(This is to avoid IFL changes) etc. from server. Thereafter it does the following.
    • It filters all the running, queued, exiting jobs from the queues it is associated with its partition/s.
    • It filters all the list of nodes which are associated with the partition/s managed by the scheduler.
    • It filters the list of all the global policies like run soft/hard limits set on the server object.
  • PBS's init script will now be reporting status of pbs server only. Schedulers will be managed by server and their status can be fetched using a qmgr command.
    • When pbs_server daemon is stopped using "qterm -s" then, it will also stop all the running scheduler processes.
    • pbs init script while shutting down pbs_server will use the "-s" option to qterm so that all schedulers also come down along with server.

Interface 8: Changes to Reservations

• Visibility: Public
• Change Control: Stable
• Details:
  • In a Multi-sched environment, reservations can be confirmed by any scheduler servicing their respective partitions.
  • After the reservations are confirmed they are assigned the partition their node solution came from.
  •  Once the reservation is confirmed, it has a partition attribute set on it to identify where it was confirmed. Similarly, the reservation queue also gets a partition attribute set on it (matching the reservation).
    • Example:

      % pbs_rsub -lselect=1:ncpus=2 -R 1030 -D1200 -I 5
      R865.centos CONFIRMED

      % pbs_rstat -f R865
      Resv ID: R865.centos
      Reserve_Name = NULL
      Reserve_Owner = root@centos
      reserve_type = 2
      reserve_state = RESV_CONFIRMED
      reserve_substate = 2
      reserve_start = Mon Feb 03 10:30:00 2020
      reserve_end = Mon Feb 03 10:50:00 2020
      reserve_duration = 1200
      queue = R865
      Resource_List.ncpus = 2
      Resource_List.nodect = 1
      Resource_List.select = 1:ncpus=2
      Resource_List.place = free
      Resource_List.walltime = 00:20:00
      schedselect = 1:ncpus=2
      resv_nodes = (vnode2:ncpus=2)
      Authorized_Users = root@centos
      server = centos
      ctime = Mon Feb 03 10:08:55 2020
      mtime = Mon Feb 03 10:09:03 2020
      interactive = 5
      Variable_List = PBS_O_LOGNAME=root,PBS_O_HOST=centos,PBS_O_MAIL=/var/spool/mail/arung,PBS_TZID=America/Los_Angeles
      euser = root
      egroup = root
      partition = P1

      % qmgr -c "l q R865"
      Queue R865
      queue_type = Execution
      total_jobs = 0
      state_count = Transit:0 Queued:0 Held:0 Waiting:0 Running:0 Exiting:0 Begun:0
      acl_user_enable = True
      acl_users = root@centos
      resources_max.ncpus = 2
      resources_available.ncpus = 2
      enabled = True
      started = False
      partition = P1

  • Once a reservation is confirmed and partition is assigned to it, it can not be re-confirmed or altered in any other partition.

  • Reservations (and their queues) confirmed by the default scheduler are marked under partition "pbs-default".

  • PBS assigns a default partition name "pbs-default" to all the reservations (and their queues) confirmed by the default scheduler. If an admin tries to assign a scheduler/queue/node partition name "pbs-default", qmgr command throws error - "Default partition name is not allowed".

Interface 9: Deleted

Interface 10: Fairshare

• Visibility: Public
• Change Control: Stable

• Unless there is only a single scheduler, the fairshare scheduling policy per whole PBS complex is no longer supported.
  • This policy is limited to each individual scheduler.
• The pbsfs command will now act on a single scheduler's fairshare usage database.
  • The new '-I' option allows the admin to specify which scheduler
    • If no '-I' option is given, pbsfs will act upon the default scheduler
    • pbsfs will now contact the server to query the location of the sched_priv for the scheduler.
      
      • Since contacting the server is now required, the server needs to be running to use pbsfs.  This was not true before.
    • If the scheduler's sched_priv is not accessible, the existing error message will be printed to stderr

      • Unable to access fairshare data

    • If no such scheduler exists, the following message will be printed to stderr
      • Scheduler <sched> does not exist
    • If a scheduler does not have its sched_priv set, the following message will be printed to stderr
      • Scheduler <sched> does not have its sched_priv set
    • Example:
      • pbsfs -s user1 10
        • sets user1's usage to 10 for the default scheduler
      • pbsfs -I sched2 -s user2 10
        • sets user2's usage to 10 for sched2.

• 
  

  Notes: 

1. What is not supported when multiple scheduler objects are present.

• With the introduction of this feature following things are not supported.
  • Run limits set on server are not supported because a scheduler object does not have a view of  the whole PBS universe.

       2. Server's backfill_depth will be default value for all the schedulers in the complex.

            Ex: Default server's backfill_depth is 1 ,1 job per each scheduler will be backfilled 

                If server's backfill_depth is set to 5 , 5 jobs from each scheduler will get backfilled

3. The pbs_statsched() IFL will return the status of all PBS scheduler status. return type is pointer to list of batch_status structure (one for each scheduler)

4. PTL framework changes :

    Multiple scheduler information can be accessed by self.server.schedulers ,

    All scheduler functions can be called from a specific scheduler as self.server.schedulers['sched_name'].<method name>.

    There is a short hand created to server.schedulers as scheds, We can use this as self.scheds['sched_name'].<method name>.