`linuxfabrik.lfops.uptimerobot_monitor`¶

Create, update or delete an UptimeRobot monitor

Synopsis¶

Manages a single UptimeRobot monitor end-to-end (create, update, pause/resume, delete) against the v2 API.
Identification is by friendly_name; the value must be unique on the account. Re-running a task with the same friendly_name updates the existing monitor in place and only reports changed=true when one of the diffable fields actually differs.
Enum-coded fields (type, sub_type, keyword_type, keyword_case_type, http_auth_type, http_method, post_type, post_content_type, disable_domain_expire_notifications, status) are accepted in their human-readable form; the module translates to the API's integer codes on write and back on read, so the diff happens on labels.
http_password and http_auth_type are not visible in the getMonitors response; when set, they are forwarded on every edit but never count as a change. type is only honoured on create - UptimeRobot does not allow changing the monitor type after the fact. status is only honoured on edit, since UptimeRobot rejects it on create.

Available since LFOps 6.0.2.

Requirements¶

python >= 3.9

Mandatory Parameters¶

friendly_name

Display name of the monitor. Used as the idempotency key, so it must be unique on the account.
Type: String.

Optional Parameters¶

alert_contacts

Alert contacts to attach to the monitor. Each item references an existing alert contact, plus the per-monitor threshold and recurrence. The list is replaced on every run; pass an empty list to clear all attached contacts. When an item has id, it is used directly. Otherwise friendly_name is resolved against getAlertContacts; an unknown name fails the play.
Type: List.
Subkeys:
- friendly_name:
  - Friendly name of an existing alert contact. Required if id is not given.
  - Type: String.
- id:
  - Numeric ID of an existing alert contact. Takes precedence over friendly_name when both are set.
  - Type: Number.
- recurrence:
  - Re-alert interval in minutes. 0 disables re-alerting.
  - Type: Number.
  - Default: 0
- threshold:
  - Alert delay in seconds. 0 means alert immediately.
  - Type: Number.
  - Default: 0

api_key

UptimeRobot API key. When unset, the module reads api_key_file (default ~/.uptimerobot) and finally falls back to the UPTIMEROBOT_API_KEY environment variable.
Type: String.

api_key_file

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

custom_http_headers

Extra HTTP headers to send with each check. Accepts either a JSON-encoded string or a plain dict; the module forwards either form to UptimeRobot unchanged.
Type: Raw.

custom_http_statuses

Override of which HTTP status codes count as up/down, in UptimeRobot's wire format (e.g. 200:0_201:0_500:1). Only forwarded as-is.
Type: String.

disable_domain_expire_notifications

disable silences UptimeRobot's domain-expiry warnings for this monitor, enable keeps them on.
Type: String. One of disable, enable.

http_auth_type

Authentication scheme used together with http_username and http_password. Like http_password, this is forwarded on every edit but never counted as a change because the API does not return it.
Type: String. One of basic, digest.

http_method

HTTP method to use for type=C(http) and type=C(keyw) monitors.
Type: String. One of delete, get, head, options, patch, post, put.

http_password

Password for HTTP basic / digest authentication. UptimeRobot does not return this field in getMonitors, so the module always forwards the value on edit but never counts it as a change.
Type: String.

http_username

Username for HTTP basic / digest authentication. Only meaningful for type=C(http) and type=C(keyw).
Type: String.

ignore_ssl_errors

When true, accept invalid or self-signed TLS certificates and only fail on connection-level errors.
Type: Bool.

interval

Check interval in seconds. UptimeRobot enforces a per-plan minimum (e.g. 30s on the Pro plan, 300s on the free plan).
Type: Number.

keyword_case_type

For type=C(keyw), cs makes the search case-sensitive, ci case-insensitive.
Type: String. One of ci, cs.

keyword_type

For type=C(keyw), exist alerts when the keyword is found in the response body, notex alerts when it is missing.
Type: String. One of exist, notex.

keyword_value

Keyword to look for in the response body. Required for type=C(keyw).
Type: String.

mwindows

Maintenance windows to attach to the monitor. Each item references an existing maintenance window. The list is replaced on every run; pass an empty list to detach all windows. When an item has id, it is used directly. Otherwise friendly_name is resolved against getMWindows; an unknown name fails the play.
Type: List.
Subkeys:
- friendly_name:
  - Friendly name of an existing maintenance window. Required if id is not given.
  - Type: String.
- id:
  - Numeric ID of an existing maintenance window. Takes precedence over friendly_name when both are set.
  - Type: Number.

port

Custom port number. Only consulted by UptimeRobot when type=C(port) and sub_type=C(custom).
Type: Number.

post_content_type

Content-Type header for the request body.
Type: String. One of content/json, text/html.

post_type

Format of the post_value payload.
Type: String. One of key-value, raw data.

post_value

Payload to send with POST / PUT / PATCH requests.
Type: String.

state

present creates the monitor when missing, or updates it in place when present. absent deletes the monitor identified by friendly_name. When the monitor does not exist, the module exits with changed=false.
Type: String. One of absent, present.
Default: present

status

up un-pauses the monitor, paused pauses it. Only honoured on edit; UptimeRobot rejects this field on create. To create a monitor in a paused state, create it first and then re-run the task with status=C(paused).
Type: String. One of paused, up.

sub_type

For type=C(port), which protocol/port preset to use. custom means "use the explicit port value".
Type: String. One of custom, ftp, http, https, imap, pop3, smtp.

timeout

Per-check timeout in seconds.
Type: Number.

type

Monitor type. http for HTTS checks, keyw for keyword checks, ping for ICMP, port for TCP-port checks, beat for heartbeat. Required when creating a new monitor. Only honoured on create; UptimeRobot rejects type changes on existing monitors.
Type: String. One of beat, http, keyw, ping, port.

url

URL, host, IP or heartbeat token to monitor. Required when creating a new monitor; ignored on update if unchanged.
Type: String.

Examples¶

# 1) Create-or-update a simple HTTPS monitor. Idempotent: re-running with the
#    same values reports `changed=false`.
- name: 'Manage a simple HTTPS monitor'
  linuxfabrik.lfops.uptimerobot_monitor:
    api_key: '{{ uptimerobot__api_key }}'
    friendly_name: '001 www.example.com/index.php/login'
    url: 'https://www.example.com/index.php/login'
    type: 'http'
    interval: 120
    http_method: 'get'
    alert_contacts:
      - friendly_name: 'monitoring@example.com'
        threshold: 1
        recurrence: 0
    mwindows:
      - friendly_name: 'weekly mon 03:30-05:30'
    state: 'present'

# 2) Keyword monitor: alert if the page does NOT contain "OK" (case-insensitive).
- name: 'Keyword-monitor a healthcheck endpoint'
  linuxfabrik.lfops.uptimerobot_monitor:
    friendly_name: '001 healthcheck.example.com'
    url: 'https://healthcheck.example.com/status'
    type: 'keyw'
    keyword_type: 'notex'
    keyword_case_type: 'ci'
    keyword_value: 'OK'
    interval: 60
    alert_contacts:
      - friendly_name: 'monitoring@example.com'
        threshold: 1
        recurrence: 0
    state: 'present'

# 3) Pause / resume a monitor. The API key is taken from the environment.
- name: 'Pause a monitor before a deployment'
  linuxfabrik.lfops.uptimerobot_monitor:
    friendly_name: '001 www.example.com/index.php/login'
    status: 'paused'
    state: 'present'
  environment:
    UPTIMEROBOT_API_KEY: '{{ uptimerobot__api_key }}'

- name: 'Resume the monitor after the deployment'
  linuxfabrik.lfops.uptimerobot_monitor:
    friendly_name: '001 www.example.com/index.php/login'
    status: 'up'
    state: 'present'

# 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 '
  register: 'ur_to_pause'

- name: 'Pause them all'
  linuxfabrik.lfops.uptimerobot_monitor:
    friendly_name: '{{ item.friendly_name }}'
    status: 'paused'
    state: 'present'
  loop: '{{ ur_to_pause.monitors }}'
  loop_control:
    label: '{{ item.friendly_name }}'

# 5) Delete a stale monitor.
- name: 'Delete a monitor'
  linuxfabrik.lfops.uptimerobot_monitor:
    friendly_name: 'old-monitor'
    state: 'absent'

# Debugging hints:
#   * Tail per-call syslog: `journalctl --identifier ansible-uptimerobot_monitor --follow`
#   * Inspect the structured operation summary: `register: r` + `debug var=r.debug`.
#   * Use `--check --diff` to preview create/update/delete without API writes.

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: - interval friendly_name: 001 www.example.com/index.php/login monitor_id: 794294 operation: update

monitor

On create or update, the monitor object as returned by UptimeRobot's newMonitor / editMonitor. On delete, the last known state of the monitor as returned by getMonitors. Empty dict when there was nothing to delete (state=absent and monitor not present). In check mode, a synthetic preview reflecting what the run would have written.
Type: Dictionary.
Returned: always.
Sample:

yaml friendly_name: 001 www.example.com/index.php/login id: 794294 interval: 120 status: up type: http url: https://www.example.com/index.php/login

Authors¶

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

linuxfabrik.lfops.uptimerobot_monitor¶