Skip to content

GitLab

Commit 8798f713 authored by Samir Noir's avatar Samir Noir 🧀
Browse files

Add documentation for jobs API

parent 3c2d1e6e
Hide whitespace changes
Inline Side-by-side
app/controllers/apidocs_controller.rb
View file @ 8798f713
......@@ -14,11 +14,13 @@ class ApidocsController < ActionController::Base
key :name, 'Apache 2.0'
end
end
tag do
key :name, 'reference-api'
key :description, "Reference-api expose Grid'5000's reference-repository, "\
"the single source of truth about sites, clusters, nodes, and network topology."
end
tag do
key :name, 'version'
key :description, 'The version API allows to consult reference-repository history.'
......@@ -31,6 +33,14 @@ class ApidocsController < ActionController::Base
"reservations are also returned by this API."
end
tag do
key :name, 'job'
key :description, "The job API is used to submit a job on Grid'5000 "\
"or to manage an existing one. This API use OAR, more informations "\
"about job management on Grid'5000 can be found on [the wiki]"\
"(https://www.grid5000.fr/w/Advanced_OAR)"
end
tag do
key :name, 'deployment'
key :description, 'The deployment API is use if you want to deploy a specific '\
......@@ -238,7 +248,9 @@ class ApidocsController < ActionController::Base
ResourcesController,
VersionsController,
DeploymentsController,
JobsController,
Grid5000::Deployment,
Grid5000::Job,
self
].freeze
......
app/controllers/deployments_controller.rb
View file @ 8798f713
......@@ -69,6 +69,12 @@ class DeploymentsController < ApplicationController
response 201 do
content :'plain/text'
key :description, 'Deployment successfully created.'
header :'Location' do
key :description, 'Location of the new deployment resource.'
schema do
key :type, :string
end
end
end
end
end
......
app/controllers/jobs_controller.rb
View file @ 8798f713
......@@ -13,9 +13,73 @@
# limitations under the License.
class JobsController < ApplicationController
include Swagger::Blocks
LIMIT = 50
LIMIT_MAX = 500
swagger_path "/sites/{siteId}/jobs" do
operation :get do
key :summary, 'List jobs'
key :description, 'Fetch the list of all jobs for site. Jobs ordering is by ' \
'descending date of submission.'
key :tags, ['job']
[:siteId, :offset, :limit, :jobQueue, :jobName, :jobState,
:jobUser, :jobResources].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :JobCollection
end
end
key :description, 'Deployment collection.'
end
end
operation :post do
key :summary, 'Submit job'
key :description, "Submit a new job."
key :tags, ['job']
parameter do
key :$ref, :siteId
end
request_body do
key :description, 'Job submission payload.'
key :required, true
content 'application/json' do
schema do
key :'$ref', :JobSubmit
end
end
content 'application/x-www-form-urlencoded' do
schema do
key :'$ref', :JobSubmit
end
end
end
response 201 do
content :'plain/text'
key :description, 'Job successfully created.'
header :'Location' do
key :description, 'Location of the new job.'
schema do
key :type, :string
end
end
end
end
end
# List jobs
def index
allow :get, :post; vary_on :accept
......@@ -60,6 +124,58 @@ class JobsController < ApplicationController
end
end
swagger_path "/sites/{siteId}/jobs/{jobId}" do
operation :get do
key :summary, 'Get job'
key :description, 'Fetch a specific job.'
key :tags, ['job']
[:siteId, :jobId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :Job
end
end
key :description, 'The job item.'
end
response 404 do
content :'text/plain'
key :description, 'Job not found.'
end
end
operation :delete do
key :summary, 'Delete job'
key :description, 'Ask for deletion of job.'
key :tags, ['job']
[:siteId, :jobId].each do |param|
parameter do
key :$ref, param
end
end
response 202 do
key :description, 'Job deletion accepted. Note that the deletion is not '\
'immediate, the job can be poll until error state.'
header :'Location' do
key :description, 'Location of the job resource'
schema do
key :type, :string
end
end
end
end
end
# Display the details of a job
def show
allow :get, :delete; vary_on :accept
......
app/models/grid5000/job.rb
View file @ 8798f713
......@@ -17,6 +17,8 @@ require 'time'
module Grid5000
# Class representing a Grid5000 job.
class Job
include Swagger::Blocks
attr_reader :errors
READ_ONLY_ATTRIBUTES = %i[uid user_uid submitted_at started_at
......@@ -32,6 +34,409 @@ module Grid5000
attr_reader(*READ_ONLY_UNDERSCORE_ATTRIBUTES)
attr_accessor(*READ_WRITE_ATTRIBUTES)
# Swagger doc
swagger_component do
parameter :jobId do
key :name, :jobId
key :in, :path
key :description, 'ID of job to fetch.'
key :required, true
key :type, :string
end
parameter :jobQueue do
key :name, :queue
key :in, :path
key :description, 'Filter jobs with a specific queue.'
key :required, false
key :type, :string
end
parameter :jobProject do
key :name, :project
key :in, :query
key :description, 'Filter jobs with a specific project name.'
key :required, false
key :type, :string
end
parameter :jobUser do
key :name, :user
key :in, :query
key :description, 'Filter jobs with a specific owner.'
key :required, false
key :type, :string
end
parameter :jobName do
key :name, :name
key :in, :query
key :description, 'Filter jobs with a specific name.'
key :required, false
key :type, :string
end
parameter :jobState do
key :name, :state
key :in, :query
key :description, 'Filter jobs by state (waiting, launching, running, '\
'hold, error, terminated), as a comma-separated list.'
key :required, false
key :type, :string
end
parameter :jobResources do
key :name, :resources
key :in, :query
key :description, "Get more details (assigned_nodes and resources_by_types) "\
"for each job in the list. Should be 'yes' or 'no'."
key :required, false
key :type, :string
key :pattern, '^(no|yes)$'
key :default, 'no'
end
schema :OarEvent do
key :required, [:uid, :created_at, :type, :description]
property :uid do
key :type, :integer
key :description, 'The OAR event unique ID.'
key :example, 7002358
end
property :created_at do
key :type, :integer
key :description, 'The timestamp of event creation.'
key :example, 1605713978
end
property :type do
key :type, :string
key :description, 'The event type.'
key :example, 'SEND_KILL_JOB'
end
property :description do
key :type, :string
key :description, 'A description of the event.'
key :example, '[Leon] Send the kill signal to oarexec on frontend for job 4242'
end
end
schema :JobCollection do
allOf do
schema do
key :'$ref', :BaseApiCollection
end
schema do
key :'$ref', :JobItems
end
schema do
property :links do
key :type, :array
items do
key :'$ref', :links
end
key :example, [{
'rel':'self',
'href':'/3.0/sites/grenoble/jobs',
'type':'application/vnd.grid5000.item+json'
},
{
'rel':'parent',
'href':'/3.0/sites/grenoble',
'type':'application/vnd.grid5000.item+json'
}]
end
end
end
end
schema :JobItems do
key :required, [:items]
property :items do
key :type, :array
items do
key :'$ref', :Job
end
end
end
schema :Job do
key :required, [:uid, :user_uid, :user, :walltime, :queue, :state,
:project, :name, :types, :mode, :command, :submitted_at,
:started_at, :stopped_at, :message, :properties,
:directory, :events]
property :uid do
key :type, :integer
key :description, 'The unique identifier of the job.'
key :example, 42
end
property :user_uid do
key :type, :string
key :description, "The job's owner."
key :example, 'user'
end
property :user_uid do
key :type, :string
key :description, "The job's owner."
key :example, 'user'
end
property :walltime do
key :type, :integer
key :description, 'The walltime of job, in seconds.'
key :example, 3600
end
property :queue do
key :type, :string
key :description, "The job's queue."
key :example, 'default'
end
property :state do
key :type, :string
key :description, 'The state of job, can be: waiting, launching, ' \
'running, hold, error, terminated.'
key :example, 'running'
end
property :project do
key :type, :string
key :description, "The job's project."
key :example, 'running'
end
property :name do
key :type, :string
key :description, "The job's name."
key :example, 'My awesome job'
end
property :type do
key :type, :array
items do
key :type, :string
end
key :description, "The OAR job's types."
key :example, ['deploy', 'night']
end
property :mode do
key :type, :string
key :description, "The job's mode ('INTERACTIVE or PASSIVE')."
key :example, 'PASSIVE'
end
property :command do
key :type, :string
key :description, "The job's command."
key :example, './my-script.sh'
end
property :submitted_at do
key :type, :integer
key :description, "The job's submission time, as a timestamp."
key :example, 1605712132
end
property :started_at do
key :type, :integer
key :description, "The job's start time, as a timestamp."
key :example, 1605712452
end
property :stopped_at do
key :type, :integer
key :description, "The job's stop time (if already stopped), as a timestamp."
key :example, 1605713607
end
property :message do
key :type, :string
key :description, "Various OAR message."
key :example, 'FIFO scheduling OK'
end
property :properties do
key :type, :string
key :description, "SQL constraints on OAR's resources."
key :example, "(cluster='troll') AND maintenance = 'NO'"
end
property :directory do
key :type, :string
key :description, 'Directory of command launch.'
key :example, '/home/user/'
end
property :events do
key :type, :array
key :description, 'List of OAR events for job (like a kill request, and '\
'then the killed by OAR event.'
items do
key :'$ref', :OarEvent
end
end
property :assigned_nodes do
key :type, :array
key :description, 'List of nodes assigned to job (if any).'
items do
key :type, :string
key :format, :hostname
end
key :example, ['dahu-20.grenoble.grid5000.fr', 'dahu-21.grenoble.grid5000.fr']
end
property :resources_by_types do
key :type, :object
key :description, "Assigned resources to job, by type ('cores', 'vlans', "\
"subnets, disks)."
property :cores do
key :type, :array
items do
key :type, :string
key :format, :hostname
end
key :example, ['dahu-20.grenoble.grid5000.fr/1', 'dahu-21.grenoble.grid5000.fr/1']
end
property :vlans do
key :type, :array
items do
key :type, :integer
end
key :example, [4]
end
property :disks do
key :type, :array
items do
key :type, :string
end
key :example, ['sdb.yeti-1.grenoble.grid5000.fr',
'sdb.yeti-2.grenoble.grid5000.fr']
end
property :subnets do
key :type, :array
items do
key :type, :string
end
key :example, ['10.134.92.0/22']
end
end
property :links do
key :type, :array
items do
key :'$ref', :Links
end
key :example, [{
'rel':'self',
'href':'/3.0/sites/grenoble/jobs/42',
'type':'application/vnd.grid5000.item+json'
},
{
'rel':'parent',
'href':'/3.0/sites/grenoble',
'type':'application/vnd.grid5000.item+json'
}]
end
end
schema :JobSubmit do
key :required, [:command]
property :resources do
key :type, :string
key :description, 'A description of the resources you want to book for '\
'your job, in OAR format.'
key :example, 'nodes=3,walltime=02:00'
key :default, 'nodes=1'
end
property :directory do
key :type, :string
key :description, 'The directory in which the command will be launched.'
key :default, '/home/{user}'
key :example, '~/my-job'
end
property :command do
key :type, :string
key :description, 'The command to execute when the job starts.'
key :example, './my-script.sh'
end
property :stderr do
key :type, :string
key :description, 'The path to the file that will contain the STDERR '\
'output of your command.'
key :default, '{directory}/OAR.%jobid%.stderr'
key :example, '{directory}/OAR.%jobid%.stderr'
end
property :stdout do
key :type, :string
key :description, 'The path to the file that will contain the STDOUT '\
'output of your command.'
key :default, '{directory}/OAR.%jobid%.stdout'
key :example, '{directory}/OAR.%jobid%.stdout'
end
property :properties do
key :type, :string
key :description, 'A string containing SQL constraints on the resources '\
'(see OAR documentation for more details).'
key :example, "(cluster='troll')"
end
property :reservation do
key :type, :string
key :description, 'If you want your job to be scheduled at a specific '\
'date, as a UNIX timestamp, OR a string containing a date in a '\
'reasonable format.'
key :example, '2020-19-12 14:35:00 GMT+0100'
end
property :types do
key :type, :array
key :description, 'An array of job types.'
items do
key :type, :string
end
key :example, ['deploy', 'night']
end
property :project do
key :type, :string
key :description, 'A project name to link your job to, set by default '\
'to the default one specified (if so) in UMS (known as GGA).'
key :example, 'my-lab-project'
end
property :name do
key :type, :string
key :description, 'A job name.'
key :example, 'My awesome job'
end
property :queue do
key :type, :string
key :description, 'A job queue.'
key :default, 'default'
key :example, 'production'
end
end
end
def initialize(h = {})
@errors = []
h = h.to_h.symbolize_keys
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment