Merge branch '3531-sort-jobs-with-pipelines' closes #3531
[arvados.git] / sdk / cli / bin / arv-run-pipeline-instance
1 #!/usr/bin/env ruby
2
3 # == Synopsis
4 #
5 #  arv-run-pipeline-instance --template pipeline-template-uuid [options] [--] [parameters]
6 #  arv-run-pipeline-instance --instance pipeline-instance-uuid [options]
7 #
8 # Satisfy a pipeline template by finding or submitting a mapreduce job
9 # for each pipeline component.
10 #
11 # == Options
12 #
13 # [--template uuid] Use the specified pipeline template.
14 #
15 # [--template path] Load the pipeline template from the specified
16 #                   local file.
17 #
18 # [--instance uuid] Use the specified pipeline instance.
19 #
20 # [-n, --dry-run] Do not start any new jobs or wait for existing jobs
21 #                 to finish. Just find out whether jobs are finished,
22 #                 queued, or running for each component
23 #
24 # [--submit] Do not try to satisfy any components. Just
25 #                          create an instance, print its UUID to
26 #                          stdout, and exit.
27 #
28 # [--no-wait] Make only as much progress as possible without entering
29 #             a sleep/poll loop.
30 #
31 # [--no-reuse] Do not reuse existing jobs to satisfy pipeline
32 #              components. Submit a new job for every component.
33 #
34 # [--debug] Print extra debugging information on stderr.
35 #
36 # [--debug-level N] Increase amount of debugging information. Default
37 #                   1, possible range 0..3.
38 #
39 # [--status-text path] Print plain text status report to a file or
40 #                      fifo. Default: /dev/stdout
41 #
42 # [--status-json path] Print JSON status report to a file or
43 #                      fifo. Default: /dev/null
44 #
45 # == Parameters
46 #
47 # [param_name=param_value]
48 #
49 # [param_name param_value] Set (or override) the default value for
50 #                          every parameter with the given name.
51 #
52 # [component_name::param_name=param_value]
53 # [component_name::param_name param_value]
54 # [--component_name::param_name=param_value]
55 # [--component_name::param_name param_value] Set the value of a
56 #                                            parameter for a single
57 #                                            component.
58 #
59 class WhRunPipelineInstance
60 end
61
62 $application_version = 1.0
63
64 if RUBY_VERSION < '1.9.3' then
65   abort <<-EOS
66 #{$0.gsub(/^\.\//,'')} requires Ruby version 1.9.3 or higher.
67   EOS
68 end
69
70 $arvados_api_version = ENV['ARVADOS_API_VERSION'] || 'v1'
71 $arvados_api_host = ENV['ARVADOS_API_HOST'] or
72   abort "#{$0}: fatal: ARVADOS_API_HOST environment variable not set."
73 $arvados_api_token = ENV['ARVADOS_API_TOKEN'] or
74   abort "#{$0}: fatal: ARVADOS_API_TOKEN environment variable not set."
75
76 begin
77   require 'arvados'
78   require 'rubygems'
79   require 'json'
80   require 'pp'
81   require 'trollop'
82   require 'google/api_client'
83 rescue LoadError => l
84   puts $:
85   abort <<-EOS
86 #{$0}: fatal: #{l.message}
87 Some runtime dependencies may be missing.
88 Try: gem install arvados pp google-api-client json trollop
89   EOS
90 end
91
92 def debuglog(message, verbosity=1)
93   $stderr.puts "#{File.split($0).last} #{$$}: #{message}" if $debuglevel >= verbosity
94 end
95
96 module Kernel
97   def suppress_warnings
98     original_verbosity = $VERBOSE
99     $VERBOSE = nil
100     result = yield
101     $VERBOSE = original_verbosity
102     return result
103   end
104 end
105
106 if $arvados_api_host.match /local/
107   # You probably don't care about SSL certificate checks if you're
108   # testing with a dev server.
109   suppress_warnings { OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE }
110 end
111
112 class Google::APIClient
113   def discovery_document(api, version)
114     api = api.to_s
115     return @discovery_documents["#{api}:#{version}"] ||=
116       begin
117         response = self.execute!(
118                                  :http_method => :get,
119                                  :uri => self.discovery_uri(api, version),
120                                  :authenticated => false
121                                  )
122         response.body.class == String ? JSON.parse(response.body) : response.body
123       end
124   end
125 end
126
127
128 # Parse command line options (the kind that control the behavior of
129 # this program, that is, not the pipeline component parameters).
130
131 p = Trollop::Parser.new do
132   version __FILE__
133   opt(:dry_run,
134       "Do not start any new jobs or wait for existing jobs to finish. Just find out whether jobs are finished, queued, or running for each component.",
135       :type => :boolean,
136       :short => :n)
137   opt(:status_text,
138       "Store plain text status in given file.",
139       :short => :none,
140       :type => :string,
141       :default => '/dev/stdout')
142   opt(:status_json,
143       "Store json-formatted pipeline in given file.",
144       :short => :none,
145       :type => :string,
146       :default => '/dev/null')
147   opt(:no_wait,
148       "Do not wait for jobs to finish. Just look up status, submit new jobs if needed, and exit.",
149       :short => :none,
150       :type => :boolean)
151   opt(:no_reuse,
152       "Do not reuse existing jobs to satisfy pipeline components. Submit a new job for every component.",
153       :short => :none,
154       :type => :boolean)
155   opt(:debug,
156       "Print extra debugging information on stderr.",
157       :type => :boolean)
158   opt(:debug_level,
159       "Set debug verbosity level.",
160       :short => :none,
161       :type => :integer)
162   opt(:template,
163       "UUID of pipeline template, or path to local pipeline template file.",
164       :short => :none,
165       :type => :string)
166   opt(:instance,
167       "UUID of pipeline instance.",
168       :short => :none,
169       :type => :string)
170   opt(:submit,
171       "Do not try to satisfy any components. Just create a pipeline instance and output its UUID.",
172       :short => :none,
173       :type => :boolean)
174   opt(:run_here,
175       "Manage the pipeline in process.",
176       :short => :none,
177       :type => :boolean)
178   stop_on [:'--']
179 end
180 $options = Trollop::with_standard_exception_handling p do
181   p.parse ARGV
182 end
183 $debuglevel = $options[:debug_level] || ($options[:debug] && 1) || 0
184
185 if $options[:instance]
186   if $options[:template] or $options[:submit]
187     abort "#{$0}: syntax error: --instance cannot be combined with --template or --submit."
188   end
189 elsif not $options[:template]
190   puts "error: you must supply a --template or --instance."
191   p.educate
192   abort
193 end
194
195 if $options[:run_here] == $options[:submit]
196   abort "#{$0}: syntax error: you must supply either --run-here or --submit."
197 end
198
199 # Suppress SSL certificate checks if ARVADOS_API_HOST_INSECURE
200
201 module Kernel
202   def suppress_warnings
203     original_verbosity = $VERBOSE
204     $VERBOSE = nil
205     result = yield
206     $VERBOSE = original_verbosity
207     return result
208   end
209 end
210
211 if ENV['ARVADOS_API_HOST_INSECURE']
212   suppress_warnings { OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE }
213 end
214
215 # Set up the API client.
216
217 $client ||= Google::APIClient.
218   new(:host => $arvados_api_host,
219       :application_name => File.split($0).last,
220       :application_version => $application_version.to_s)
221 $arvados = $client.discovered_api('arvados', $arvados_api_version)
222 $arv = Arvados.new api_version: 'v1'
223
224
225 class PipelineInstance
226   def self.find(uuid)
227     result = $client.execute(:api_method => $arvados.pipeline_instances.get,
228                              :parameters => {
229                                :uuid => uuid
230                              },
231                              :authenticated => false,
232                              :headers => {
233                                authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
234                              })
235     j = JSON.parse result.body, :symbolize_names => true
236     unless j.is_a? Hash and j[:uuid]
237       debuglog "Failed to get pipeline_instance: #{j[:errors] rescue nil}", 0
238       nil
239     else
240       debuglog "Retrieved pipeline_instance #{j[:uuid]}"
241       self.new(j)
242     end
243   end
244   def self.create(attributes)
245     result = $client.execute(:api_method => $arvados.pipeline_instances.create,
246                              :body_object => {
247                                :pipeline_instance => attributes
248                              },
249                              :authenticated => false,
250                              :headers => {
251                                authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
252                              })
253     j = JSON.parse result.body, :symbolize_names => true
254     unless j.is_a? Hash and j[:uuid]
255       abort "\n#{Time.now} -- pipeline_template #{@template[:uuid]}\nFailed to create pipeline_instance: #{j[:errors] rescue nil} #{j.inspect}"
256     end
257     debuglog "Created pipeline instance: #{j[:uuid]}"
258     self.new(j)
259   end
260   def save
261     result = $client.execute(:api_method => $arvados.pipeline_instances.update,
262                              :parameters => {
263                                :uuid => @pi[:uuid]
264                              },
265                              :body_object => {
266                                :pipeline_instance => @attributes_to_update
267                              },
268                              :authenticated => false,
269                              :headers => {
270                                authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
271                              })
272     j = JSON.parse result.body, :symbolize_names => true
273     unless j.is_a? Hash and j[:uuid]
274       debuglog "Failed to save pipeline_instance: #{j[:errors] rescue nil}", 0
275       nil
276     else
277       @attributes_to_update = {}
278       @pi = j
279     end
280   end
281   def []=(x,y)
282     @attributes_to_update[x] = y
283     @pi[x] = y
284   end
285   def [](x)
286     @pi[x]
287   end
288   protected
289   def initialize(j)
290     @attributes_to_update = {}
291     @pi = j
292   end
293 end
294
295 class JobCache
296   def self.get(uuid)
297     @cache ||= {}
298     result = $client.execute(:api_method => $arvados.jobs.get,
299                              :parameters => {
300                                :uuid => uuid
301                              },
302                              :authenticated => false,
303                              :headers => {
304                                authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
305                              })
306     @cache[uuid] = JSON.parse result.body, :symbolize_names => true
307   end
308   def self.where(conditions)
309     result = $client.execute(:api_method => $arvados.jobs.list,
310                              :parameters => {
311                                :limit => 10000,
312                                :where => conditions.to_json
313                              },
314                              :authenticated => false,
315                              :headers => {
316                                authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
317                              })
318     list = JSON.parse result.body, :symbolize_names => true
319     if list and list[:items].is_a? Array
320       list[:items]
321     else
322       []
323     end
324   end
325   def self.create(pipeline, component, job, create_params)
326     @cache ||= {}
327
328     body = {job: no_nil_values(job)}.merge(no_nil_values(create_params))
329
330     result = $client.execute(:api_method => $arvados.jobs.create,
331                              :body_object => body,
332                              :authenticated => false,
333                              :headers => {
334                                authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
335                              })
336     j = JSON.parse result.body, :symbolize_names => true
337     if j.is_a? Hash and j[:uuid]
338       @cache[j[:uuid]] = j
339     else
340       debuglog "create job: #{j[:errors] rescue nil} with attributes #{body}", 0
341
342       msg = ""
343       j[:errors].each do |err|
344         msg += "Error creating job for component #{component}: #{err}\n"
345       end
346       msg += "Job submission was: #{body.to_json}"
347
348       $client.execute(:api_method => $arvados.logs.create,
349                       :body_object => {
350                         :log => {
351                           :object_uuid => pipeline[:uuid],
352                           :event_type => 'stderr',
353                           :owner_uuid => pipeline[:owner_uuid],
354                           :properties => {"text" => msg}
355                         }
356                       },
357                       :authenticated => false,
358                       :headers => {
359                         authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
360                       })
361       nil
362     end
363   end
364
365   protected
366
367   def self.no_nil_values(hash)
368     hash.reject { |key, value| value.nil? }
369   end
370 end
371
372 class WhRunPipelineInstance
373   attr_reader :instance
374
375   def initialize(_options)
376     @options = _options
377   end
378
379   def fetch_template(template)
380     if template.match /[^-0-9a-z]/
381       # Doesn't look like a uuid -- use it as a filename.
382       @template = JSON.parse File.read(template), :symbolize_names => true
383       if !@template[:components]
384         abort ("#{$0}: Template loaded from #{template} " +
385                "does not have a \"components\" key")
386       end
387     else
388       result = $client.execute(:api_method => $arvados.pipeline_templates.get,
389                                :parameters => {
390                                  :uuid => template
391                                },
392                                :authenticated => false,
393                                :headers => {
394                                  authorization: 'OAuth2 '+ENV['ARVADOS_API_TOKEN']
395                                })
396       @template = JSON.parse result.body, :symbolize_names => true
397       if !@template[:uuid]
398         abort "#{$0}: fatal: failed to retrieve pipeline template #{template} #{@template[:errors].inspect rescue nil}"
399       end
400     end
401     self
402   end
403
404   def fetch_instance(instance_uuid)
405     @instance = PipelineInstance.find(instance_uuid)
406     @template = @instance
407     self
408   end
409
410   def apply_parameters(params_args)
411     params_args.shift if params_args[0] == '--'
412     params = {}
413     while !params_args.empty?
414       if (re = params_args[0].match /^(--)?([^-].*?)=(.+)/)
415         params[re[2]] = re[3]
416         params_args.shift
417       elsif params_args.size > 1
418         param = params_args.shift.sub /^--/, ''
419         params[param] = params_args.shift
420       else
421         abort "\n#{Time.now} -- pipeline_template #{@template[:uuid]}\nSyntax error: I do not know what to do with arg \"#{params_args[0]}\""
422       end
423     end
424
425     @components = @template[:components].dup
426
427     errors = []
428     @components.each do |componentname, component|
429       component[:script_parameters].each do |parametername, parameter|
430         parameter = { :value => parameter } unless parameter.is_a? Hash
431         value =
432           (params["#{componentname}::#{parametername}"] ||
433            parameter[:value] ||
434            (parameter[:output_of].nil? &&
435             (params[parametername.to_s] ||
436              parameter[:default])) ||
437            nil)
438         if value.nil? and
439             ![false,'false',0,'0'].index parameter[:required]
440           if parameter[:output_of]
441             next
442           end
443           errors << [componentname, parametername, "required parameter is missing"]
444         end
445         debuglog "parameter #{componentname}::#{parametername} == #{value}"
446         component[:script_parameters][parametername] = value
447       end
448     end
449     if !errors.empty?
450       abort "\n#{Time.now} -- pipeline_template #{@template[:uuid]}\nErrors:\n#{errors.collect { |c,p,e| "#{c}::#{p} - #{e}\n" }.join ""}"
451     end
452     debuglog "options=" + @options.pretty_inspect
453     self
454   end
455
456   def setup_instance
457     if @instance
458       @instance[:properties][:run_options] ||= {}
459       if @options[:no_reuse]
460         # override properties of existing instance
461         @instance[:properties][:run_options][:enable_job_reuse] = false
462       else
463         # Default to "enable reuse" if not specified. (This code path
464         # can go away when old clients go away.)
465         if @instance[:properties][:run_options][:enable_job_reuse].nil?
466           @instance[:properties][:run_options][:enable_job_reuse] = true
467         end
468       end
469     else
470       @instance = PipelineInstance.
471         create(components: @components,
472                properties: {
473                  run_options: {
474                    enable_job_reuse: !@options[:no_reuse]
475                  }
476                },
477                pipeline_template_uuid: @template[:uuid],
478                state: ($options[:submit] ? 'RunningOnServer' : 'RunningOnClient'))
479     end
480     self
481   end
482
483   def run
484     moretodo = true
485     interrupted = false
486
487     job_creation_failed = 0
488     while moretodo
489       moretodo = false
490       @components.each do |cname, c|
491         job = nil
492         owner_uuid = @instance[:owner_uuid]
493         # Is the job satisfying this component already known to be
494         # finished? (Already meaning "before we query API server about
495         # the job's current state")
496         c_already_finished = (c[:job] &&
497                               c[:job][:uuid] &&
498                               !c[:job][:success].nil?)
499         if !c[:job] and
500             c[:script_parameters].select { |pname, p| p.is_a? Hash and p[:output_of]}.empty?
501           # No job yet associated with this component and is component inputs
502           # are fully specified (any output_of script_parameters are resolved
503           # to real value)
504           job = JobCache.create(@instance, cname, {
505             :script => c[:script],
506             :script_parameters => c[:script_parameters],
507             :script_version => c[:script_version],
508             :repository => c[:repository],
509             :nondeterministic => c[:nondeterministic],
510             :output_is_persistent => c[:output_is_persistent] || false,
511             :runtime_constraints => c[:runtime_constraints],
512             :owner_uuid => owner_uuid,
513           }, {
514             # This is the right place to put these attributes when
515             # dealing with new API servers.
516             :minimum_script_version => c[:minimum_script_version],
517             :exclude_script_versions => c[:exclude_minimum_script_versions],
518             :find_or_create => (@instance[:properties][:run_options].andand[:enable_job_reuse] &&
519                                 !c[:nondeterministic]),
520             :filters => c[:filters]
521           })
522           if job
523             debuglog "component #{cname} new job #{job[:uuid]}"
524             c[:job] = job
525           else
526             debuglog "component #{cname} new job failed", 0
527             job_creation_failed += 1
528           end
529         end
530
531         if c[:job] and c[:job][:uuid]
532           if (c[:job][:running] or
533               not (c[:job][:finished_at] or c[:job][:cancelled_at]))
534             # Job is running so update copy of job record
535             c[:job] = JobCache.get(c[:job][:uuid])
536           end
537
538           if c[:job][:success]
539             # Populate script_parameters of other components waiting for
540             # this job
541             @components.each do |c2name, c2|
542               c2[:script_parameters].each do |pname, p|
543                 if p.is_a? Hash and p[:output_of] == cname.to_s
544                   debuglog "parameter #{c2name}::#{pname} == #{c[:job][:output]}"
545                   c2[:script_parameters][pname] = c[:job][:output]
546                   moretodo = true
547                 end
548               end
549             end
550             unless c_already_finished
551               # This is my first time discovering that the job
552               # succeeded. (At the top of this loop, I was still
553               # waiting for it to finish.)
554               if c[:output_is_persistent]
555                 # I need to make sure a resources/wants link is in
556                 # place to protect the output from garbage
557                 # collection. (Normally Crunch does this for me, but
558                 # here I might be reusing the output of someone else's
559                 # job and I need to make sure it's understood that the
560                 # output is valuable to me, too.)
561                 wanted = c[:job][:output]
562                 debuglog "checking for existing persistence link for #{wanted}"
563                 @my_user_uuid ||= $arv.user.current[:uuid]
564                 links = $arv.link.list(limit: 1,
565                                        filters:
566                                        [%w(link_class = resources),
567                                         %w(name = wants),
568                                         %w(tail_uuid =) + [@my_user_uuid],
569                                         %w(head_uuid =) + [wanted]
570                                        ])[:items]
571                 if links.any?
572                   debuglog "link already exists, uuid #{links.first[:uuid]}"
573                 else
574                   newlink = $arv.link.create link: \
575                   {
576                     link_class: 'resources',
577                     name: 'wants',
578                     tail_kind: 'arvados#user',
579                     tail_uuid: @my_user_uuid,
580                     head_kind: 'arvados#collection',
581                     head_uuid: wanted,
582                     owner_uuid: owner_uuid
583                   }
584                   debuglog "added link, uuid #{newlink[:uuid]}"
585                 end
586               end
587             end
588           elsif c[:job][:running] ||
589               (!c[:job][:started_at] && !c[:job][:cancelled_at])
590             # Job is still running
591             moretodo = true
592           elsif c[:job][:cancelled_at]
593             debuglog "component #{cname} job #{c[:job][:uuid]} cancelled."
594           end
595         end
596       end
597       @instance[:components] = @components
598       report_status
599
600       if @options[:no_wait]
601         moretodo = false
602       end
603
604       # If job creation fails, just give up on this pipeline instance.
605       if job_creation_failed > 0
606         moretodo = false
607       end
608
609       if moretodo
610         begin
611           sleep 10
612         rescue Interrupt
613           debuglog "interrupt", 0
614           interrupted = true
615           break
616         end
617       end
618     end
619
620     ended = 0
621     succeeded = 0
622     failed = 0
623     @components.each do |cname, c|
624       if c[:job]
625         if c[:job][:finished_at] or c[:job][:cancelled_at] or (c[:job][:running] == false and c[:job][:success] == false)
626           ended += 1
627           if c[:job][:success] == true
628             succeeded += 1
629           elsif c[:job][:success] == false or c[:job][:cancelled_at]
630             failed += 1
631           end
632         end
633       end
634     end
635
636     success = (succeeded == @components.length)
637
638     # A job create call failed. Just give up.
639     if job_creation_failed > 0
640       debuglog "job creation failed - giving up on this pipeline instance", 0
641       success = false
642       failed += 1
643     end
644
645     if interrupted
646      if success
647         @instance[:state] = 'Complete'
648      else
649         @instance[:state] = 'Paused'
650       end
651     else
652       if ended == @components.length or failed > 0
653         @instance[:state] = success ? 'Complete' : 'Failed'
654       end
655     end
656
657     debuglog "pipeline instance state is #{@instance[:state]}"
658
659     # set components_summary
660     components_summary = {"todo" => @components.length - ended, "done" => succeeded, "failed" => failed}
661     @instance[:components_summary] = components_summary
662
663     @instance.save
664   end
665
666   def cleanup
667     if @instance and @instance[:state] == 'RunningOnClient'
668       @instance[:state] = 'Paused'
669       @instance.save
670     end
671   end
672
673   def uuid
674     @instance[:uuid]
675   end
676
677   protected
678
679   def report_status
680     @instance.save
681
682     if @options[:status_json] != '/dev/null'
683       File.open(@options[:status_json], 'w') do |f|
684         f.puts @components.pretty_inspect
685       end
686     end
687
688     if @options[:status_text] != '/dev/null'
689       File.open(@options[:status_text], 'w') do |f|
690         f.puts ""
691         f.puts "#{Time.now} -- pipeline_instance #{@instance[:uuid]}"
692         namewidth = @components.collect { |cname, c| cname.size }.max
693         @components.each do |cname, c|
694           jstatus = if !c[:job]
695                       "-"
696                     elsif c[:job][:running]
697                       "#{c[:job][:tasks_summary].inspect}"
698                     elsif c[:job][:success]
699                       c[:job][:output]
700                     elsif c[:job][:cancelled_at]
701                       "cancelled #{c[:job][:cancelled_at]}"
702                     elsif c[:job][:finished_at]
703                       "failed #{c[:job][:finished_at]}"
704                     elsif c[:job][:started_at]
705                       "started #{c[:job][:started_at]}"
706                     else
707                       "queued #{c[:job][:created_at]}"
708                     end
709           f.puts "#{cname.to_s.ljust namewidth} #{c[:job] ? c[:job][:uuid] : '-'.ljust(27)} #{jstatus}"
710         end
711       end
712     end
713   end
714 end
715
716 runner = WhRunPipelineInstance.new($options)
717 begin
718   if $options[:template]
719     runner.fetch_template($options[:template])
720   else
721     runner.fetch_instance($options[:instance])
722   end
723   runner.apply_parameters(p.leftovers)
724   runner.setup_instance
725   if $options[:submit]
726     runner.instance.save
727     puts runner.instance[:uuid]
728   else
729     runner.run
730   end
731 rescue Exception => e
732   runner.cleanup
733   raise e
734 end