7.7 Working with Facts and Constraints

You can incorporate facts and constraints into the custom jobs you create to manage your data center resources using Orchestrator. You should already be familiar with the concepts related to controlling jobs using job facts and constraints. For more information, see the following JDL links:

This section contains the following topics:

7.7.1 Grid Objects and Facts

Every resource and service discovered in an Orchestrator-enabled network is identified and abstracted as an object. Within the Orchestrator management framework, objects are stored within an addressable database called a grid. Every grid object has an associated set of facts and constraints that define the properties and characteristics of either physical or virtual resources. In essence, by building, deploying, and running jobs on the Orchestrator Server, you can individually change the functionality of any and all system resources by managing an object’s facts and constraints.

The components that have facts include resources, users, jobs, repositories, and vmhosts. The grid server assigns default values to each of the component facts, although they can be changed at anytime by the administrator unless they are read-only.

However, the developer desires certain constraints to be used for a job and might specify these in the policy. These comprise a set of logical clauses and operators that are compared with the respective component’s fact values when the job is run by the Job Scheduling Manager.

Remember, all properties appear in the job context, which is an environment where constraints are evaluated. These constraints provide a multilevel filter for a job in order to ensure the best quality of service the grid can provide.

7.7.2 Defining Job Elements

When you deploy a job, you can include an XML policy file that defines constraints and facts. Because every job is a grid object with its own associated set of facts (job.id, etc.), it already has a set of predefined facts, so jobs can also be controlled by changing job arguments at run time.

As a job writer, you define the set of job arguments in the job args fact space. Your goal in writing a job is to define the specific elements a job user is permitted to change. These job argument facts are defined in the job XML policy for every given job.

The job argument fact values are passed to a job when the job is run. Consequently, the Orchestrator Server run command passes in the job arguments. Similarly, for the job scheduler, you can define which job arguments you want to schedule or run a job. You can also specify job arguments for the Web portal.

For example, in the following quickie.job example, the number of joblets allowed to run and the amount of sleep time between running joblets are set by the arguments numJoblets and sleeptime as defined in the policy file for the job. If no job arguments are defined, the client cannot affect the job:

...
          # Launch the joblets
          numJoblets = self.getFact("jobargs.numJoblets")
          print 'Launching ', numJoblets, ' joblets'

          self.schedule(quickieJoblet, numJoblets)

class quickieJoblet(Joblet):

     def joblet_started_event(self):
          sleeptime = self.getFact("jobargs.sleeptime")          time.sleep(sleeptime)

To view the complete example, see quickie.job.

As noted, when running a job, you can pass in a policy file, which is another method the client can use to control job behavior. Policy files can pass in additional constraints to the job, such as how a resource might be selected or how the job runs. The policy file is an XML file defined with the .policy extension.

For example, as shown below, you can pass in a policy for the job named quickie, with an additional constraint to limit the chosen resources to those with a Linux OS. Suppose a policy file name linux.policy in the directory named /mypolicies with this content:

<constraint type=?resource?>    <eq fact="resource.os.family" value="linux" /></constraint>

To start the quickie job using the additional policy, you would enter the following command:

>zos run quickie --policyfile=/mypolicies/linux.policy

7.7.3 Job Arguments and Parameter Lists

Part of a job’s static definition might include job arguments. A job argument defines what values can be passed in when a job is invoked. This allows the developer to statically define and control how a job behaves, while the administrator can modify policy values.

You define job arguments in an XML policy file named with the same base name as the job. The example job cracker.jdl, for example, has an associated policy file named cracker.policy. The cracker.policy file contains entries for the <jobargs> namespace, as shown in the following partial example from cracker.policy.

     <jobargs>
          <fact name="cryptpw"
           type="String"
           description="Password of abc"
           value="4B3lzcNG/Yx7E"
           />
        <fact name="joblets"
           type="Integer"
           description="joblets to run"
           value="100"
           />
     </jobargs>

The above policy defines two facts in the jobargs namespace for the cracker job. One is a String fact named cryptpw with a default value. The second jobargs fact is an integer named joblets. Both of these facts have default values so they do not require been set on job invocation. If the default value was omitted, then job would require that the two facts be set on job invocation. The job will not start unless all required job argument facts are supplied at job invocation. The default values of job argument facts can be overridden at job invocation. Job arguments are passed to a job when the job is invoked. This is done in one of the following ways:

  • From the ZOS run command from the CLI, as shown in the following example:

    >zos run cracker cryptpw="dkslsl"
    
  • From within a JDL job script when invoking a child job, as shown in the following job JDL fragment:

    self.runjob("cracker", { "cryptpw" : "asdfa" } )
    
  • From the Orchestrator scheduler, either with the Orchestrator console or by a .sched file.