[FEED] Rules documentation improvements

[adamsilkcm]

I would consider this a separate issue from https://github.com/tribe29/ansible-collection-tribe29.checkmk/issues/153

Provide your feedback Documentation contains:

options:
    rule:
        description: Definition of the rule as returned by the Checkmk API.
        required: true
        type: dict

The examples show:

    rule:
        conditions: {
            "host_labels": [],
            "host_name": {
                "match_on": [
                    "test1.tld"
                ],
                "operator": "one_of"
            },
            "host_tags": [],
            "service_labels": []
        }
        properties: {
            "comment": "Warning at 80%\nCritical at 90%\n",
            "description": "Allow higher memory usage",
            "disabled": false,
            "documentation_url": "https://github.com/tribe29/ansible-collection-tribe29.checkmk/blob/main/plugins/modules/rules.py"
        }
        value_raw: "{'levels': (80.0, 90.0)}"

Example rule from API:

{
  "links": [
...
  ],
  "domainType": "rule",
  "id": "1222a909-cf52-4f9d-b43a-cab4f31d925d",
  "title": "sometitle",
  "members": {},
  "extensions": {
    "ruleset": "active_checks:http",
    "folder": "/",
    "folder_index": 0,
    "properties": {
      "description": "example",
      "disabled": false
    },
    "value_raw": "{'name': 'example', 'host': {'port': 80}, 'mode': ['url', {'uri': '/'}]}",
    "conditions": {
      "host_tags": [],
      "host_labels": [
        {
          "key": "role",
          "operator": "is",
          "value": "web"
        }
      ],
      "service_labels": []
    }
  }
}

So while rule is a dict as per documentation, mixing YAML and JSON in the example, while technically correct, is a bit confusing, especially when keeping it all as JSON would make grabbing what the API returns a bit easier.

Definition of the rule as returned by the Checkmk API. is also a confusing as ruleset is broken out from the rule even though it is a part of the extensions the API returns that contains the other items in the example rule: properties, conditions, value_raw.

Component Name

rules module

Collection Version

$ ansible-galaxy collection list
Collection          Version
------------------- -------
tribe29.checkmk     0.11.0

[robin-checkmk]

Hi @adamsilkcm and thanks for reporting this! We are quite swamped right now, but I will get to this as soon as I can. If you have a concrete idea, what we should change, do let us know, or create a pull request yourself. :)

[robin-checkmk]

@diademiemi if I may tag you here: Maybe you can improve the documentation yourself, before I try to find the right words?

[x86-39]

Sorry for the late reply.

I split the top level fields into conditions, properties and value_raw so it's easier to modify these in Ansible if needed. I'm not quite sure what you're suggesting gets changed here, what do you think would be better for the documentation?

[adamsilkcm]

I split the top level fields into conditions, properties and value_raw

The documentation only says:

options:
    rule:
        description: Definition of the rule as returned by the Checkmk API.
        required: true
        type: dict

It does not mention conditions, properties, or value_raw except in the examples. It also does not mention why these values and not any of the others under extensions such as folder or why ruleset is in a property that's not part of the rule dictionary. So the Definition of the rule as returned by the Checkmk API. really means only some parts of it, some of which go into this dictionary (which on likely has to alter anyway due to the python/yaml/list/tuple thing going on in https://github.com/tribe29/ansible-collection-tribe29.checkmk/pull/79 which one wouldn't know about from the documentation and would have to find those issues and solutions) and some of which go into ruleset and some of which don't go anywhere.

As for improvements:

• split the rule dictionary up (this isn't a documentation suggestion, but since ruleset has already been split off might as well split the rest up) or split up the rule variable definition into rule.conditions, rule.properties, rule.value_raw and better define their format (value_raw is differently formatted than properties and it would be good to mention why or at least how each ought to be formatted)
• mention the issue with copying from api output, to not use the webUI's raw_value (see https://github.com/tribe29/ansible-collection-tribe29.checkmk/issues/153#issuecomment-1249249276 and https://github.com/tribe29/ansible-collection-tribe29.checkmk/pull/79#issuecomment-1216395663 ), and list/tuple punctuation gotchas (I don't care if it's technically not related to the ansible and has to do with how the api handles things; if it impacts how users interact with the ansible, it deserves a mention in the documentation as opposed to a merged PR)

[geof77]

Hi @adamsilkcm , @diademiemi , you might want to check the modifications I propose in PR #231. I'm still not sure about the "as returned by the CheckMK API", but it might be time to delete this as all parameters can now be YAML style (doc updated accordingly), with the notable exception of value_raw, which still has to be Pyhton-compatible. However you can now format it as you wish (have a look at the examples in #231) because the module fetches the API representation before comparisons (see PR #233).

I'd also wish that "ruleset" is moved under "rule" because it is a parameter of the rule. But then "rule" could as well be removed and everything under it move up one level.

[github-actions[bot]]

This issue has been stale for 60 days. It will close in 7 days.

[github-actions[bot]]

This issue has been stale for 60 days. It will close in 7 days.

[robin-checkmk]

I will be out for some days, and when I return, I want to wrap this up. So everyone involved: Can we a) Do something concrete here, or b) close this issue and create a follow-up with overall documentation improvements for the rule module?

I appreciate every input here, but I will also close this, if there is no activity at all.