Skip to content

linuxfabrik.lfops.uptimerobot_mwindow

Create, update or delete an UptimeRobot maintenance window

Synopsis

  • Manages a single UptimeRobot maintenance window (create, update of the editable parts, pause/resume, delete) against the v2 API.
  • Identification is by friendly_name. When omitted on state=present, the module synthesises one as "<type> [<value>] <start_time>-<end_time>" (e.g. weekly mon 03:30-05:30, daily 02:00-02:30) so re-runs stay idempotent without having to invent a name.
  • Update is intentionally narrow - only duration and status are diffed against the existing window. Changing the schedule itself (type, value, start_time, end_time) means changing friendly_name too (or the synthesised one), which results in a new window being created next to the old one rather than an in-place edit. This also avoids UptimeRobot's inconsistent start_time storage (older windows are kept as local HH:MM, newer ones as UTC HH:MM:SS) confusing the diff.
  • Provide either end_time or duration, not both. When end_time is given, the duration in minutes is computed automatically (wrapping over midnight when end_time < start_time).

Available since LFOps 6.0.2.

Optional Parameters

api_key

  • UptimeRobot API key. See uptimerobot_monitor for the resolution order.
  • Type: String.

api_key_file

  • Path to a file whose first line is the UptimeRobot API key. Tilde-expanded.
  • Type: String.
  • Default: ~/.uptimerobot

duration

  • Duration of the window in minutes. Mutually exclusive with end_time.
  • Type: Number.

end_time

  • HH:MM wall-clock time. Combined with start_time to compute duration automatically; wraps over midnight when end < start. Mutually exclusive with duration.
  • Type: String.

friendly_name

  • Display name of the window. When omitted on state=present, the module synthesises one from type, value, start_time and end_time; in that case all four must be given. Required on state=absent.
  • Type: String.

start_time

  • For type=C(once), an RFC3339 timestamp. For type=C(daily)/weekly/monthly, an HH:MM wall-clock time.
  • Type: String.

state

  • present creates or updates, absent deletes. When the window does not exist on state=absent, the module exits with changed=false.
  • Type: String. One of absent, present.
  • Default: present

status

  • active un-pauses the window, paused pauses it. Only honoured on edit; UptimeRobot rejects this field on create.
  • Type: String. One of active, paused.

type

  • Recurrence type. Required when creating a new window.
  • Type: String. One of daily, monthly, once, weekly.

value

  • For type=C(weekly), the weekday as a label (mon, tue, ..., sun). Multiple weekdays can be passed as a dash-joined list (e.g. mon-wed-fri). For type=C(monthly), the day of the month as a number 1..31 (passed through unchanged). For type=C(once) and type=C(daily), unused.
  • Type: String.

Examples

# 1) Create-or-update a weekly window. friendly_name is auto-synthesised as
#    "weekly mon 03:30-05:30" so re-runs are idempotent without naming it.
- name: 'Weekly Monday-night maintenance window'
  linuxfabrik.lfops.uptimerobot_mwindow:
    type: 'weekly'
    value: 'mon'
    start_time: '03:30'
    end_time: '05:30'
    state: 'present'

# 2) Daily window (no `value` for type=daily).
- linuxfabrik.lfops.uptimerobot_mwindow:
    type: 'daily'
    start_time: '02:00'
    end_time: '02:30'
    state: 'present'

# 3) Override the auto-name and pass a literal duration in minutes.
- linuxfabrik.lfops.uptimerobot_mwindow:
    friendly_name: 'cert-renewal'
    type: 'weekly'
    value: 'sun'
    start_time: '04:00'
    duration: 120
    state: 'present'

# 4) Pause an existing window without changing schedule.
- linuxfabrik.lfops.uptimerobot_mwindow:
    friendly_name: 'weekly mon 03:30-05:30'
    status: 'paused'
    state: 'present'

# 5) Delete a stale window by friendly_name.
- linuxfabrik.lfops.uptimerobot_mwindow:
    friendly_name: 'old-window'
    state: 'absent'

Return Values

debug

  • Diagnostic information about the operation (one of create, update, delete, noop, each optionally suffixed with (check_mode)). Stable enough to assert against, not stable enough to be load-bearing.
  • Type: Dictionary.
  • Returned: always.

  • Sample:

    yaml diff_fields: - duration friendly_name: weekly mon 03:30-05:30 mwindow_id: 12345 operation: update

mwindow

  • On create or update, the maintenance window as returned by UptimeRobot's newMWindow / editMWindow. On delete, the last known state of the window. Empty dict when there was nothing to delete. In check mode, a synthetic preview reflecting what the run would have written.
  • Type: Dictionary.
  • Returned: always.

Authors

  • Linuxfabrik GmbH, Zurich, Switzerland (info (at) linuxfabrik (dot) ch)