Form.yml, submit.yml.erb, and documentation

[novosirj (Ryan Novosielski)]

Hi there,

I’m not sure whether it’s the fact that I don’t really know Ruby, or whether the documentation is a little thin on this part if you’re starting fresh (or both), but I’m having trouble understanding well how forms/submit files work.

1. I basically understand, from the note at the bottom of this page:

https://osc.github.io/ood-documentation/latest/app-development/interactive/submit.html

…that if you’re using one of the predefined attributes, you don’t have to muck around with “script:” in the submit.yml.erb, and that that list is here:

https://osc.github.io/ood-documentation/latest/app-development/interactive/form.html#app-development-interactive-form-predefined-attributes

But it says that listed here are the most common attributes. Is that all of them, or is there a longer list someplace?

On this page:

https://osc.github.io/ood-documentation/latest/enable-desktops/custom-job-submission.html

…there’s a mention that you should avoid native: where possible, and use these instead of resorting to that, if possible:

http://www.rubydoc.info/gems/ood_core/OodCore/Job/Script

I’ve managed to figure out that, for example, if I want to add a “Reservation” field for an app, I should do:

form:
  - reservation_id

…and then in submit.yml.erb, do:

script:
  reservation_id: "<%= reservation_id %>"

But is that correct? It just seems a little redundant.

2. Additionally, I’d like to able to have a freeform text field that would allow a user to specify other Slurm options without having to set up attributes for every one of them (most of which wouldn’t be used that often). However, I’d like it to be possible to leave that blank, as I imagine it would be most of the time. So I did something like this in form.yml:

form:
  - extra_slurm_options

…and in submit.yml.erb:

script:
  native:
    - "<%- unless extra_slurm_options.empty? -%><%= extra_slurm_options %><%- end -%>"

…but when I hit the launch button, I get:

Failed to submit session with the following error:

sbatch: error: Unable to open file

From looking in the /var/log/ondemand-nginx/$USER/error.log, I can see that it is resulting in this batch line:

App 2517 output: [2021-12-07 22:12:01 -0500 ]  INFO "execve = [{\"SLURM_CONF\"=>\"/etc/slurm/slurm.conf\"}, \"/usr/bin/sbatch\", \"-D\", \"/home/novosirj/ondemand/data/sys/dashboard/batch_connect/sys/bc_desktop/amarel/output/45b81c12-8e8e-4690-acf2-30a8efee90c3\", \"-J\", \"sys/dashboard/sys/bc_desktop/amarel\", \"-o\", \"/home/novosirj/ondemand/data/sys/dashboard/batch_connect/sys/bc_desktop/amarel/output/45b81c12-8e8e-4690-acf2-30a8efee90c3/output.log\", \"--reservation\", \"OOD_test\", \"-p\", \"main\", \"-t\", \"01:00:00\", \"--export\", \"NONE\", \"-c\", \"1\", \"--mem=1G\", \"\", \"--parsable\", \"-M\", \"amarel\"]"

Which it apparently does not like. Is there some other form of check for emptiness I need to be doing there, or specifying something different when the value is empty?

Also, if I want someone to be able to specify a few options, would I need multiple blanks, or is there a better way to do this? I guess I envisioned being able to add whichever additional options as they would on an sbatch command line. This is functionality on our existing setup, but we’re completely redoing that as the person who built it mucked around with a lot of the app files in /var vs. configuring them via /etc, and their method of doing this had multiple blanks but didn’t allow you to leave any of them blank (suggesting that you repeat options if you only needed one of them).

3. This is pretty neat stuff, being able to specify a cluster as a wildcard (BTW, this page seems to be somewhat out of date as it specifies you’ll need an app for each cluster when you don’t anymore necessarily: 2. Add a Cluster — Open OnDemand 3.0.3 documentation), which is documented here:

https://osc.github.io/ood-documentation/latest/app-development/interactive/form.html?highlight=cluster#configuring-which-cluster-to-submit-to

…which will generate a select widget. There’s also information about how to rename the options. I’m assuming when one specifies cluster: "*" that what it’s pulling from is /etc/ood/config/clusters.d/*.yml. Is there a simple way to get it, instead of having to define vanity names here manually, to use the title: field under metadata: from the applicable cluster definition?

4. I assume contributions to the documentation are welcomed/encouraged? What’s the best way to do that, just edits via GitHub? There are some parts of this where it seems like the information that you’d need to create a given workflow are in a few different places, and there are some references to preferring to do one thing over another but no example of how to do that thing (related to some of the questions above).

[novosirj (Ryan Novosielski)]

Also, the docs here seem to be incorrect:

https://osc.github.io/ood-documentation/latest/app-development/interactive/form.html?highlight=cluster#configuring-which-cluster-to-submit-to

Specifically:

# ${HOME}/ondemand/dev/different_select_cluster/form.yml
---
form:
  - cluster
attributes:
  cluster:
    widget: "select"
    options:
      - ["cluster1", "The first cluster"]
      - ["cluster2", "The second cluster"]

…this doesn’t work for me unless I flip the cluster name and different text. I guess that could be my first documentation contribution/allow me to make up for that goose chase from earlier today on OOD_SSHHOST_ALLOWLIST.

[jeff.ohrstrom]

OK - I’m deconstructing your first note a bit.

1. I found a list of predefined items here.

https://osc.github.io/ood-documentation/latest/app-development/interactive/form.html#predefined-attributes

2. This may work better for you.

script:
  <%- unless extra_slurm_options.empty? -%>
  native:
    - "<%= extra_slurm_options %>"
  <%- end -%>

3. I don’t think I follow this or know exactly what you’re getting at. Cluster names are taken from the name of the file in cluster.d, not metadata inside any file. So cluster.d/my_cool_cluster.yml is my_cool_cluster directly.

4. Yes please and thank you. Pull requests are always welcome! Especially little fixes like this I can just pull right it. Github has a feature where you can edit things in the web directly, so you don’t need to deal with pulling it down and so on.

As to larger re-organizing of the documentation - I get it. You’re right the docs are a bit sparse and wide. I’m working to group things better and have common stuff like this more discoverable. The 2.1 docs should look a little better (you can checkout the progress if you look at develop instead of latest in the URL).

[novosirj (Ryan Novosielski)]

1. This page mentions before the list “The most commonly used predefined attributes are given as:” which makes it sound like there might be more. Is that true, or is that just how it’s written?

2. Thanks, I’ll give something like that a shot. I’m wondering if that will work, given I have native: defined already, but can try moving the top line inside the existing native: too if need be.

3. We’re mostly on the same page. So inside our file for one of our clusters, we have:

---
v2:
  metadata:
    title: Amarel Cluster
  login:
    host: amarel.hpc.rutgers.edu
  job:
    cluster: amarel
    bin: "/usr/bin"
    conf: "/etc/slurm/slurm.conf"
    adapter: slurm
  batch_connect:
    basic:
      script_wrapper: |
        module purge
        %s
    vnc:
      websockify_cmd: '/usr/bin/websockify'
      header: |
        export PATH=/opt/TurboVNC/bin:$PATH

…where you can see there’s a title: for this cluster that gets used a couple of other places in OOD (the shell app in the top menu for one). It would be nice to reuse this in forms when specifying cluster: "*", using that title instead of either just the cluster name or having to manually define the options in the widget, if there’s some way to do it.

Re: docs, will have a look at the 2.1 docs and see if I have anything to offer there. I know I personally find it hard sometimes to remember what I would have needed to know when I was newer at something, but also can’t write about it till I understand it, so there’s a narrow window. Thanks!

[novosirj (Ryan Novosielski)]

#2 works nicely for a single option, thank you. Is there a simple way to make it work for something like, just for example:

--exclusive --dependency=singleton --threads-per-core=2

If I were to put that in the blank right now, I get:

Failed to submit session with the following error:

/usr/bin/sbatch: unrecognized option ‘–exclusive --dependency=singleton --threads-per-core=2’
Try “sbatch --help” for more information

Is there a better/alternative way to do it, or should I just offer a number of blanks, or…?

[jeff.ohrstrom]

I was worried that may not work. Looks like you’ve got to split the single string into multiple arguements. Here’s how to do that.

I’m not sure what happens if you have an emtpy string here (no extra args) so you may need that if block here too.

<%-
   args = extra_slurm_options.split
-%>
script:
  native:
    <%- args.each do |arg| -%>
    - "<%= arg %>"
    <%- end -%>

[novosirj (Ryan Novosielski)]

Thanks much; I thought it might be something like that. Works great, and it will make some people at our site very happy.

The way I ultimately applied what you suggested earlier worked too, BTW (let me know if you see any risks I might not have contemplated):

native:
    - "-c"
    - "<%= num_cores.blank? ? 1 : num_cores.to_i %>"
    - "--mem=<%= memory_gigs %>G"
  <%- unless extra_slurm_options.empty? -%>
    - "<%= extra_slurm_options %>"
  <%- end -%>

I had a mention here earlier about that field not overriding fields in the actual form and needing to use the --arg=<arg> form of the flags vs. -a arg, but that seems to have been user error or something. Both work as you’d expect.