document automigration caveats and "host!" option

[hjoliver]

From cylc/cylc-flow#6623 (comment) -

The idea was to condemn the host first (i.e. ask workflows to migrate nicely), then mop up any stragglers with the "force" mode.

OK that's fine. Leave the decision on when to force it up to the humans.

We should document that though, as some will assume the options are migrate-all or kill-all, and not think of migrate-if-possible before changing the global config again to kill the rest.

We should also document the circumstances under which workflows will not successfully auto-migrate.

[hjoliver]

Note as per the linked issue, we should not call hostname! "force condemned" - the host is condemned regardless; the option just implies we should shut its workflows down rather than attempt to migrate them.

[oliver-sanders]

Note as per the linked issue, we should not call hostname! "force condemned" - the host is condemned regardless; the option just implies we should shut its workflows down rather than attempt to migrate them.

@hjoliver Suggest an alternative, or I'll stick with force.

[hjoliver]

I did suggest an alternative - on the linked issue where we were discussing it. Summary:

"Force condemn" doesn't make sense, and simply replacing the word "force" with something else isn't going to help much. That being the case we need to rethink how to describe the relevant concepts - which isn't difficult.

"Condemned" means "sentenced to some future, typically negative, fate". A condemned host is going to be shut down (or whatever) soon, so we need we need to get the workflows off it. Such a host is condemned from the moment it is declared to be condemned, with no need for "forcing". It doesn't just become condemned later on, once the workflows have gone.

---

The concepts we need to document are simply:

Condemned hosts have been sentenced to death (figuratively speaking) so:

• new workflows will not be started on them
• existing workflows need to be stopped (with !) or migrated (without !) off them

---

The two options for what to do with workflows on a condemned host already have perfectly good names: migrate and stop.

I can't see any problem with simply documenting this as stated.

(There's no actual config item called "force condemn" that we have to think of a name for.)

[oliver-sanders]

Not particularly interested in the debate, just need a name you're happy with.

migrate and stop.

Ok, will use "migrate mode" and "stop mode".

[hjoliver]

Not particularly interested in the debate,

Me neither - but we have to give reasons for why something should be changed. Then, it's only a debate if someone else disagrees with those reasons (or the conclusions that follow from them).

[oliver-sanders]

Turns out this fas already well documented, I just didn't look very hard.

https://cylc.github.io/cylc-doc/stable/html/plugins/main-loop/built-in/cylc.flow.main_loop.auto_restart.html#module-cylc.flow.main_loop.auto_restart