kuma_control Role

This role manages monitoring tasks for Uptime Kuma by authenticating, pausing, and resuming specified monitors via the Uptime Kuma API.

Description

The kuma_control role provides a streamlined way to interact with Uptime Kuma's API. It handles authentication, pauses monitoring for specified monitors, and resumes monitoring after verifying their availability. The role is modular, allowing you to include specific tasks (token, pause, or start) based on your requirements.

Installation

1. Ensure that Ansible is installed on your system. The recommended version is at least 2.17.
2. Clone this repository or add the role to your existing project.
3. Ensure that the following dependencies are available:
   • Python with the requests library (for API calls)
   • Access to the Uptime Kuma API

Variables

The role uses the following variables:

• kuma_control_base_url: The base URL of the Uptime Kuma API. Example: https://uptime-kuma.example.com/api.

• kuma_control_api_pw: The password for the Uptime Kuma admin user.

• kuma_control_monitor: A comma-separated string or list of monitor IDs to manage. Example: "1,2,3" or [1, 2, 3].

• kuma_control_step: Specifies the task file to include. Options are:

  • token: Authenticate and retrieve an access token.
  • pause: Pause monitoring for the specified monitors.
  • start: Resume monitoring for the specified monitors.

Usage

Example Playbook

- name: Manage Uptime Kuma Monitors
  hosts: all
  vars:
    kuma_control_base_url: "https://uptime-kuma.example.com/api"
    kuma_control_api_pw: "your_password"
    kuma_control_monitor: "1,2,3"
  pre_tasks:
    - name: Include kuma_control role for token
      ansible.builtin.include_role:
        name: kuma_control
      vars:
        kuma_control_step: token

  tasks:
    - name: Include kuma_control role for pause
      ansible.builtin.include_role:
        name: kuma_control
      vars:
        kuma_control_step: pause

    - name: Include kuma_control role for start
      ansible.builtin.include_role:
        name: kuma_control
      vars:
        kuma_control_step: start

Advanced Configuration

You can customize the role's behavior by setting the following variables:

- name: Advanced Configuration Example
  hosts: all
  vars:
    kuma_control_base_url: "https://uptime-kuma.example.com/api"
    kuma_control_api_pw: "your_password"
    kuma_control_monitor: [1, 2, 3]
  tasks:
    - name: Include kuma_control role for token
      ansible.builtin.include_role:
        name: kuma_control
      vars:
        kuma_control_step: token

Features

• Authentication: Retrieves an access token from the Uptime Kuma API.
• Pause Monitoring: Pauses monitoring for the specified monitors.
• Resume Monitoring: Resumes monitoring after verifying the availability of the target URLs.
• Retry Mechanisms: Retries API calls to handle transient failures.
• Modular Design: Dynamically includes tasks based on the kuma_control_step variable.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your changes.
3. Submit a pull request describing your changes.

License

This project is licensed under the AGPL License. The AGPL license requires that modifications to the software be disclosed when distributed or made available over a network. For more information, see the LICENSE file.