Help needed: Document template parameters you know

Development
1

Hello,

over the time, Foreman gathered a lot of template parameters. I am starting an attempt to document them all and mark those which can be deprecated (e.g. same functionality under different names or template types - debian vs redhat).

I need your help! I can probably document all the bare-metal provisioning related, however we have many more, plugins and bunch of katello-related stuff. Please spend a minute and review this list and fill description for those you know what they do! Thank you.

I will be taking this list and turning it into a YAML so Foreman would actually check for description presence. Something like this (rough proposal):

---
#
# Documentation for template parameters. Rules when editing:
#
# * Prefer lower-case-dash-separated parameter names.
# * Keep description short and on point.
# * Try to keep the list sorted
#
00_example_parameter:
  description: 'Brief description. Can be multiple sentences but no newlines.'
  context: 'Where it can be used (e.g. Kickstart, Remote execution).'
  deprecated: true

From here, this could be easily transformed into our documentation or even used within Foreman application to show on template edit page. Heck we could even do parameter competition in the edit component if we have spare cycles :slight_smile:

Foreman is a beast, let’s help our users to find what they need.

3 Likes
2

WIP proposal with initial (rough) implementation:

https://github.com/theforeman/foreman/pull/8009

Give me more ideas how this could be more useful, in my proposal I simply fail if a parameter is undocumented or deprecated. This will only be tested in test environment.

3

This is a great activity, I’ll try contirbute to the documentation for sure.

I think it would be much better to actually seed all parameters with their default values. That way user can see the values in provisioning form and can overide easily for a given host (or on other levels we support). The seed file could still read it from the YAML, like we do with the templates. Parameters today don’t have a description, but that’s trivial to add.

2 Likes
4

I am not following, we do store parameter instances in the DB:

  create_table "parameters", id: :serial, force: :cascade do |t|
    t.string "name", limit: 255
    t.text "value"
    t.integer "reference_id"
    t.datetime "created_at"
    t.datetime "updated_at"
    t.string "type", limit: 255
    t.integer "priority"
    t.boolean "hidden_value", default: false
    t.string "key_type", limit: 255
    t.text "searchable_value"
    t.index ["type", "reference_id", "name"], name: "index_parameters_on_type_and_reference_id_and_name", unique: true
  end

I am not sure how can I seed those.

5

Seed in rails means create as default values, e.g. https://github.com/theforeman/foreman/blob/develop/db/seeds.d/070-provisioning_templates.rb. So once you start the Foreman for the first time, you’d already see all parameters created as global parameters.

6

Oh I understand now. So when you create new host, it would have 40 of parameters already prefilled with default values? This could easily be bad experience too tho.

That’s indeed an interesting idea. Is having all the parameters in seeds better place than a yaml? We would need to create documentation column as well.

On the other hand, we have similar thing with settings and after all those years, I think setting defaults and descriptions should rather have been defined outside of the DB (in a yaml perhaps). It requires seeding and keeping those up-to-date.

7

We do have Override parameter, I think adding documentation column makes a lot of sense, maybe even some kind of “group” so we could possibly group them together into a tree in the UI sometimes.

8

Please vote in Preferred parameter naming

9

I agree. This will clutter the UI with a lot of parameters that are irrelevant in the majority of cases, as we are showing all of the global parameters (or any of the other parameters that match the host for that matter) on the host form. In most cases the templates have sort of a “default value” for what to do when the parameter isn’t defined, so users only need to set the parameter if they want to stray from that default.

10

However long-term it’s the best solution I think. Description really belong in here, not somewhere else. And if I want to implement descriptions, which is the main goal of this effort putting all the cleanup aside, it probably the best approach.

I’d add also new field named “group” where I’d group parameters together:

  • linux general
  • debian-based
  • redhat-based
  • windows
  • others

From here the UI team can pick up and deliver quite good experience.