[ClusterLabs] [EXT] Re: Fence Agents Format

Fri Jul 28 02:46:08 EDT 2023

Hi!

On " Manual fencing or meatware is when an administrator must manually power-cycle a machine (or unplug its storage cables) and follow up with the cluster, notifying the cluster that the machine has been fenced. This is never recommended.": Maybe also explain why: The cluster assumes that fencing is complete after some timeout. When human action is needed that way be har to impossible to guarantee.

On heading "What is given to fencing agents by fenced & stonithd": Why not rename it to "The roles of fenced and stonithd"?

The syntax example "argument=value" should be converted to formal syntax description like EBNF or ABNF (Augmented BNF for Syntax Specifications: ABNF, RFC 5234).

On " Quotation marks around the value is not necessary": Doesn't that mean effectively that quotation marks are treated literally, so there must not be any?

Before " Example cluster.conf" there should be explained whether (and if so: which) parameters have defined names.

Also when using works like "fenced" meaning the process it should use a different font as it could be confused in context like "the node was fenced".

Why is the heading named "Agent Operations and Return Values" when the parameters name seems to be "action"? I mean: Why not "Agent Actions and ..."?

On " Attribute Specifications": The section should explain which parameters are expected to be present (i.e.: "required") and which are optional (common examples).
Also for each parameter the syntax for the value expected should be outlines (after all an agent has to interpret it).

One the agent's return value: So the return value is completely defined through the "action" parameter (which obviously is required)? Is there an exit code for "action not implemented" or "agent failed/crashed"?

On " Fabric fencing must never have a reboot operation": Can (if so: how?) fenced know that some agent implements fabric fencing?

On " There should be a command line mode, too": I thing tat is underspecification. Why not use a syntax like awk (-v var=val)? That woul allow to specify more command line options later. Maybe also define option "-e" to take parameters from the environment (possibly lower-casing the names).

" existing agents tend to strip leading whitespace": What does that mean? They do, or they don't? Why is this part on the specification?
If leasing white space is allowed before "var=val", why not specify it; if it isn't, then why care to ignore?
What about empty lines in input. See my earlier comment on EBNF/ABNF.

The specification says absolutely nothing about fence agent output (when does it create output (when allowed, when required), and if so what does it output (syntax, etc). The only remark is "Output of fence_agent -o metadata", which suggests the agent should output something for some command line syntax (option "-o") which isn't specified at all. Why not showing example output (not intended to replace a proper specification)

So my comment that the specification is too incomplete to allow writing a fencing agent still stands.

Kind regards,
Ulrich Windl

-----Original Message-----
From: Users <users-bounces at clusterlabs.org> On Behalf Of Oyvind Albrigtsen
Sent: Thursday, July 13, 2023 4:45 PM
To: Cluster Labs - All topics related to open-source clustering welcomed <users at clusterlabs.org>
Subject: [EXT] Re: [ClusterLabs] Fence Agents Format

On 13/07/23 09:45 +0200, Oyvind Albrigtsen wrote:
>On 12/07/23 12:57 +0000, Windl, Ulrich wrote:
>>Hi!
>>
>>Some time ago, I had been asking for an improved fencing agent specification, because the existing documents made it impossible for me to write a fencing agent. I guess with such documentation, the questions below could have been answered as well...
>I finally got started on it a week or so ago, so hopefully I'll be
>able to upload a draft soon.
Here's my initial PR for the new dev guide:
https://github.com/ClusterLabs/fence-agents/pull/552

Oyvind
>
>
>Oyvind
>>
>>Regards,
>>Ulrich
>>
>>-----Original Message-----
>>From: Users <users-bounces at clusterlabs.org> On Behalf Of Or Raz
>>Sent: Monday, July 10, 2023 11:00 AM
>>To: users at clusterlabs.org
>>Subject: [EXT] [ClusterLabs] Fence Agents Format
>>
>>Hi all,
>>My team has been working on a new operator which uses some of your Fence Agents (FA, i.e. fence_aws, fence_ipmilan, and etc.) to remediate an unhealthy Kubernetes node (see fence-agents-remediation <https://github.com/medik8s/fence-agents-remediation> ).
>>After looking on the recommended attributes for new FAs <https://github.com/ClusterLabs/fence-agents/blob/main/doc/FenceAgentAPI.md#attribute-specifications> , and the valid action attribute values <https://github.com/ClusterLabs/fence-agents/blob/main/doc/FenceAgentAPI.md#agent-operations-and-return-values> ,
>>I have some questions on the structure/format of the FAs command attributes and their responses:
>>
>>1.	Will running a fence-agent without mentioning the action field will always choose the reboot option (e.g. the following call will reboot the node "fence_aws --access-key ACCESS_KEY --secret-key SECRET_KEY --plug i-INSTANCE_ID --region AWS_REGION")?
>>2.	Are there any must-have fields which are shared between all the FAs that you support? I assume the answer is no, since I didn't see any must fields which are mutual between fence_aws, and fence_ipmilan for instance. A must field is a field which is required for running the FA (e.g. access-key for fence_aws).
>>3.	Do the result responses to the FA are identical per action? E.g. For the reboot action, I have seen that on success I always receive `Success: Rebooted` for fence_aws, and fence_ipmilan. I am an uncertain whether that is correct for all the FAs.
>>
>>Best regards,
>>
>>OR
>>
>>_______________________________________________
>>Manage your subscription:
>>https://lists.clusterlabs.org/mailman/listinfo/users
>>
>>ClusterLabs home: https://www.clusterlabs.org/
>>

_______________________________________________
Manage your subscription:
https://lists.clusterlabs.org/mailman/listinfo/users

ClusterLabs home: https://www.clusterlabs.org/