docs(roles/uptimerobot, plugins/modules/uptimerobot_*): drop references to the standalone utr CLI and use neutral sample data

markuslf · markuslf · commit 057442783bc1 · 2026-04-29T20:11:01.000+02:00
The standalone uptimerobot-cli (`utr`) repo is going away, so cross-
referencing it in our README / CHANGELOG / module docs would dangle.
The role README's "Migrating from the utr CLI" section is replaced by a
"Read-Only Inspection" section that documents the four `*_info` modules
on their own merit; the prefix-collapse rule for monitor friendly_names
moves into the `prefix:` subkey docs where it belongs.

Top-level README, CHANGELOG and per-module DOCUMENTATION / EXAMPLES
blocks lose the "Equivalent of `utr get …`" lines and similar
comparisons. Customer-specific sample data (prefix `038`, URLs ending in
`-p-mon…`, `e-peds.ch`, `e-medicus.ch`) is replaced by neutral examples
(prefix `001`, `app.example.com`).
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 * **playbooks/setup_basic**: Add `setup_basic__skip_policycoreutils` to skip the `policycoreutils` role, matching the pattern used by the other roles in the playbook.
-* **role:uptimerobot, plugins/modules/uptimerobot_***: New role and a set of nine custom modules to manage UptimeRobot resources directly from a playbook. CRUD modules: `uptimerobot_monitor`, `uptimerobot_mwindow`, `uptimerobot_psp`, plus `uptimerobot_alert_contact` (delete only — UptimeRobot API v2 does not expose creating contacts). Read-only info modules for inspection and dynamic inventories: `uptimerobot_account_info`, `uptimerobot_monitor_info`, `uptimerobot_mwindow_info`, `uptimerobot_alert_contact_info`, `uptimerobot_psp_info` — together replacing all `utr get …` subcommands. All CRUD modules support `--check` and `--diff`, are idempotent on re-run, and translate API integer IDs to user-facing labels in both directions. The role accepts the same YAML structure as the existing `utr` CLI's `utr.yml` / `mwindows.yml` / `psps.yml` / `alertcontacts.yml`, so existing inventories migrate by copying the lists into `uptimerobot__monitors` / `__mwindows` / `__psps` / `__alert_contacts`. API key resolution: `api_key` parameter, `api_key_file` (default `~/.uptimerobot`, matching `utr` convention), or `UPTIMEROBOT_API_KEY` environment variable.
+* **role:uptimerobot, plugins/modules/uptimerobot_***: New role and a set of nine custom modules to manage UptimeRobot resources directly from a playbook. CRUD modules: `uptimerobot_monitor`, `uptimerobot_mwindow`, `uptimerobot_psp`, plus `uptimerobot_alert_contact` (delete only — UptimeRobot API v2 does not expose creating contacts). Read-only info modules for inspection and dynamic inventories: `uptimerobot_account_info`, `uptimerobot_monitor_info`, `uptimerobot_mwindow_info`, `uptimerobot_alert_contact_info`, `uptimerobot_psp_info`. All CRUD modules support `--check` and `--diff`, are idempotent on re-run, and translate API integer IDs to user-facing labels in both directions. Configuration is done via four inventory lists (`uptimerobot__monitors`, `uptimerobot__mwindows`, `uptimerobot__psps`, `uptimerobot__alert_contacts`). API key resolution: `api_key` parameter, `api_key_file` (default `~/.uptimerobot`), or `UPTIMEROBOT_API_KEY` environment variable.
 * **role:at**: Add optional variable `at__service_state` (`reloaded` / `restarted` / `started` / `stopped`) to control the running state of `atd.service` independently from boot autostart. Default behaviour is unchanged: `at__service_enabled: true` keeps the service started, `false` stops it.
 * **role:dnf_makecache**: Add optional variables `dnf_makecache__service_state` and `dnf_makecache__timer_state` to control the running state of `dnf-makecache.service` and `dnf-makecache.timer` independently from boot autostart. Default behaviour is unchanged.
 * **role:open_vm_tools**: Add optional variables `open_vm_tools__service_enabled` and `open_vm_tools__service_state`. The role previously had no way to disable / stop `vmtoolsd.service`; now the service can be managed like in the other LFOps service-wrapper roles. Default behaviour is unchanged (service enabled and started).
diff --git a/README.md b/README.md
@@ -418,7 +418,7 @@ LFOps also ships a small set of custom modules for resource types that are not c
 * **`lvm_pv`** — manage LVM physical volumes.
 * **`nextcloud_occ_app`**, **`nextcloud_occ_app_config`**, **`nextcloud_occ_system_config`** — drive Nextcloud `occ` from a playbook.
 * **`sqlite_query`** — run SQLite queries.
-* **`uptimerobot_*`** — manage UptimeRobot monitors, maintenance windows, public status pages and alert contacts; covers everything the standalone `utr` CLI does, with full idempotency, `--check`, `--diff` and a parallel set of `*_info` modules for read-only inspection. See the [`uptimerobot` role README](roles/uptimerobot/) for the full reference.
+* **`uptimerobot_*`** — manage UptimeRobot monitors, maintenance windows, public status pages and alert contacts via the [UptimeRobot API v2](https://uptimerobot.com/api/legacy/), with full idempotency, `--check`, `--diff` and a parallel set of `*_info` modules for read-only inspection. See the [`uptimerobot` role README](roles/uptimerobot/) for the full reference.
 
 Each custom module ships its own `DOCUMENTATION`, `EXAMPLES` and `RETURN` blocks; browse them with `ansible-doc linuxfabrik.lfops.<module>`.
 
diff --git a/plugins/modules/uptimerobot_account_info.py b/plugins/modules/uptimerobot_account_info.py
@@ -30,8 +30,8 @@
 
 
 EXAMPLES = r'''
-# 1) Read account quota and current usage (equivalent to `utr get account`).
-#    The API key comes from ~/.uptimerobot when no parameter is given.
+# 1) Read account quota and current usage. The API key comes from
+#    ~/.uptimerobot when no parameter is given.
 - name: 'Capture UptimeRobot account info'
   linuxfabrik.lfops.uptimerobot_account_info:
   register: 'ur_account'
diff --git a/plugins/modules/uptimerobot_alert_contact_info.py b/plugins/modules/uptimerobot_alert_contact_info.py
@@ -17,7 +17,6 @@
     - Returns the full list of alert contacts on the UptimeRobot account,
       with enum-style fields translated to human-readable labels (C(status),
       C(type)).
-    - Equivalent of C(utr get alert_contacts).
     - Read-only. Reports C(changed=false).
 author:
     - Linuxfabrik GmbH, Zurich, Switzerland (info (at) linuxfabrik (dot) ch)
@@ -38,7 +37,7 @@
 
 
 EXAMPLES = r'''
-# 1) Equivalent to `utr get alert_contacts`.
+# 1) List every alert contact on the account.
 - name: 'Capture all alert contacts'
   linuxfabrik.lfops.uptimerobot_alert_contact_info:
   register: 'ur_alert_contacts'
diff --git a/plugins/modules/uptimerobot_monitor.py b/plugins/modules/uptimerobot_monitor.py
@@ -37,7 +37,7 @@
     api_key_file:
         description:
             - Path to a file containing the UptimeRobot API key. Default
-              C(~/.uptimerobot) (compatible with the C(utr) CLI).
+              C(~/.uptimerobot).
         type: str
         required: false
     friendly_name:
@@ -274,8 +274,8 @@
     status: 'up'
     state: 'present'
 
-# 4) Bulk-pause every monitor of a given prefix (utr equivalent:
-#    `utr set monitors --status=paused --prefix=001`):
+# 4) Bulk-pause every monitor of a given prefix (e.g. before a deployment
+#    that would otherwise trigger spurious down-alerts):
 - name: 'Inventory monitors to pause'
   linuxfabrik.lfops.uptimerobot_monitor_info:
     search: '001 '
@@ -614,8 +614,8 @@ def main():
         desired_compare['mwindows'] = _normalize_desired_mwindows(desired_compare['mwindows'])
 
     # `http_password` and `http_auth_type` can't be diffed reliably because
-    # the API hides them in `getMonitors` responses (utr's table shows them
-    # masked as `*****`, our get returns them as null). Always send them
+    # the API hides them in `getMonitors` responses (the `auth_type` field
+    # comes back as null even when credentials are set). Always send them
     # through on edit when the user supplied them, but don't let them count
     # as a change.
     write_only = {'http_password', 'http_auth_type'}
diff --git a/plugins/modules/uptimerobot_monitor_info.py b/plugins/modules/uptimerobot_monitor_info.py
@@ -17,7 +17,6 @@
     - Returns the full list of monitors on the UptimeRobot account, with
       enum-style fields translated to human-readable labels (C(http_method),
       C(keyword_type), C(status), C(type), nested C(alert_contacts[].type)).
-    - Equivalent of C(utr get monitors).
     - Read-only. Reports C(changed=false).
 author:
     - Linuxfabrik GmbH, Zurich, Switzerland (info (at) linuxfabrik (dot) ch)
@@ -43,7 +42,7 @@
 
 
 EXAMPLES = r'''
-# 1) Quick ad-hoc list, equivalent to `utr get monitors`. The API key is read
+# 1) Quick ad-hoc list of every monitor on the account. The API key is read
 #    from ~/.uptimerobot when not passed.
 - name: 'Capture all monitors'
   linuxfabrik.lfops.uptimerobot_monitor_info:
diff --git a/plugins/modules/uptimerobot_mwindow.py b/plugins/modules/uptimerobot_mwindow.py
@@ -17,8 +17,7 @@
     - Create, update or delete a maintenance window on UptimeRobot.
     - Identification is by C(friendly_name). The window is auto-named
       C("<type> [<value>] <start_time>-<end_time>") when no C(friendly_name)
-      is given (e.g. C("weekly mon 03:30-05:30")), matching the convention
-      used by the C(utr) CLI.
+      is given (e.g. C("weekly mon 03:30-05:30")).
 author:
     - Linuxfabrik GmbH, Zurich, Switzerland (info (at) linuxfabrik (dot) ch)
 options:
diff --git a/plugins/modules/uptimerobot_mwindow_info.py b/plugins/modules/uptimerobot_mwindow_info.py
@@ -17,7 +17,6 @@
     - Returns the full list of maintenance windows on the UptimeRobot account,
       with enum-style fields translated to human-readable labels (C(type),
       C(value), C(status)).
-    - Equivalent of C(utr get mwindows).
     - Read-only. Reports C(changed=false).
 author:
     - Linuxfabrik GmbH, Zurich, Switzerland (info (at) linuxfabrik (dot) ch)
@@ -38,7 +37,7 @@
 
 
 EXAMPLES = r'''
-# 1) Equivalent to `utr get mwindows`.
+# 1) List every maintenance window on the account.
 - name: 'Capture all maintenance windows'
   linuxfabrik.lfops.uptimerobot_mwindow_info:
   register: 'ur_mwindows'
diff --git a/plugins/modules/uptimerobot_psp.py b/plugins/modules/uptimerobot_psp.py
@@ -54,8 +54,8 @@
         type: str
     custom_url:
         description:
-            - Alias for C(custom_domain), accepted for compatibility with the
-              C(utr) YAML format.
+            - Alias for C(custom_domain). Accepted as a backward-compatible
+              spelling.
         type: str
     password:
         description: Optional password to protect the status page.
diff --git a/plugins/modules/uptimerobot_psp_info.py b/plugins/modules/uptimerobot_psp_info.py
@@ -17,7 +17,6 @@
     - Returns the full list of public status pages on the UptimeRobot account,
       with enum-style fields translated to human-readable labels (C(sort),
       C(status)).
-    - Equivalent of C(utr get psps).
     - Read-only. Reports C(changed=false).
 author:
     - Linuxfabrik GmbH, Zurich, Switzerland (info (at) linuxfabrik (dot) ch)
@@ -38,7 +37,7 @@
 
 
 EXAMPLES = r'''
-# 1) Equivalent to `utr get psps`.
+# 1) List every public status page on the account.
 - name: 'Capture all public status pages'
   linuxfabrik.lfops.uptimerobot_psp_info:
   register: 'ur_psps'
diff --git a/roles/uptimerobot/README.md b/roles/uptimerobot/README.md
@@ -98,7 +98,7 @@ UptimeRobot's API has a few sharp edges that are useful to know up front. The mo
 
     * `prefix`:
 
-        * Optional. Customer / project / inventory prefix that gets prepended to the synthesised `friendly_name`.
+        * Optional. Customer / project / inventory prefix that gets prepended to the synthesised `friendly_name`. To keep names readable, the prefix is collapsed when the URL host already starts with it (e.g. `prefix: '001'` plus URL `https://001-app.example.com/login` becomes friendly_name `001-app.example.com/login` instead of `001 001-app.example.com/login`).
         * Type: String.
 
     * `url`:
@@ -494,41 +494,30 @@ Typical values you will see:
 Combined with `--check --diff`, the `debug` dict makes it cheap to investigate false-positive `changed: true` (typically a missing read-side translation or a desired-vs-current normalisation gap).
 
 
-## Migrating from the `utr` CLI
+## Read-Only Inspection
 
-Linuxfabrik used to drive the same configuration through the standalone `utr` CLI (`uptimerobot-cli`). Migration to this role is mechanical:
+Each resource type has a parallel `*_info` module for read-only queries -- useful for ad-hoc inspection, dynamic inventories, or driving downstream tasks:
 
-| `utr` file | Inventory variable |
+| Resource | Read-only module |
 |---|---|
-| `utr.yml` (top-level `monitors:` list) | `uptimerobot__monitors` |
-| `mwindows.yml` (top-level `mwindows:` list) | `uptimerobot__mwindows` |
-| `psps.yml` (top-level `psps:` list) | `uptimerobot__psps` |
-| `alertcontacts.yml` (top-level `alert_contacts:` list) | `uptimerobot__alert_contacts` |
+| Account | `linuxfabrik.lfops.uptimerobot_account_info` |
+| Monitors | `linuxfabrik.lfops.uptimerobot_monitor_info` |
+| Maintenance windows | `linuxfabrik.lfops.uptimerobot_mwindow_info` |
+| Alert contacts | `linuxfabrik.lfops.uptimerobot_alert_contact_info` |
+| Public status pages | `linuxfabrik.lfops.uptimerobot_psp_info` |
 
-The list items use the same field names — drop them into your inventory's `group_vars/lfops_uptimerobot.yml` (or wherever) and run the playbook. The auto-generated `friendly_name` follows the same `'<prefix> <url-without-protocol>'` (monitors) and `'<type> [<value>] <start_time>-<end_time>'` (mwindows) conventions, including the same prefix-collapse rule for URLs whose host already starts with the prefix (e.g. `prefix: '038'` plus URL `https://038-p-mon61…/icingaweb2/` becomes friendly_name `038-p-mon61…/icingaweb2/`).
-
-Read-side parity with `utr get …` is provided by four read-only modules — useful for ad-hoc inspection, dynamic inventories, or driving downstream tasks:
-
-| `utr` command | Ansible module |
-|---|---|
-| `utr get account` | `linuxfabrik.lfops.uptimerobot_account_info` |
-| `utr get monitors` | `linuxfabrik.lfops.uptimerobot_monitor_info` |
-| `utr get mwindows` | `linuxfabrik.lfops.uptimerobot_mwindow_info` |
-| `utr get alert_contacts` | `linuxfabrik.lfops.uptimerobot_alert_contact_info` |
-| `utr get psps` | `linuxfabrik.lfops.uptimerobot_psp_info` |
-
-All info modules accept `friendly_name:` to filter to a single resource and (where supported by the API) `search:` for a server-side substring filter. Enum-style fields are returned as labels (e.g. `http_method: 'get'`, `status: 'up'`), matching the user-facing parameter values you write in your inventory.
+All info modules accept `friendly_name:` to filter to a single resource and (where supported by the API) `search:` for a server-side substring filter. Enum-style fields come back as labels (e.g. `http_method: 'get'`, `status: 'up'`), matching the user-facing parameter values you write in your inventory.
 
 ```yaml
 - linuxfabrik.lfops.uptimerobot_monitor_info:
     friendly_name: '001 www.example.com'
-  register: ur_monitor
+  register: 'ur_monitor'
 
 - ansible.builtin.debug:
-    var: ur_monitor.monitors[0].interval
+    var: 'ur_monitor.monitors[0].interval'
 ```
 
-For the equivalent of `utr set monitors --status=paused`, loop the regular `uptimerobot_monitor` module with `state: 'present'` and `status: 'paused'` over the result of `uptimerobot_monitor_info`. Same pattern works for the `utr set psps --status=paused` / `--status=active` workflow:
+To bulk-pause / -resume monitors or status pages, loop the matching CRUD module with `state: 'present'` over the result of the `*_info` module:
 
 ```yaml
 - linuxfabrik.lfops.uptimerobot_psp_info:
