README.md

ansible-uptime-kuma

This collection contains modules that allow to configure Uptime Kuma with Ansible.

Python version 3.7+ and Ansible version 2.9+ are required.

Supported Uptime Kuma versions:

Uptime Kuma	ansible-uptime-kuma	uptime-kuma-api
1.21.3 - 1.23.2	1.0.0 - 1.2.0	1.0.0+
1.17.0 - 1.21.2	0.1.0 - 0.14.0	0.1.0 - 0.13.0

Installation

This collection requires the python module uptime-kuma-api to communicate with Uptime Kuma. It can be installed using pip:

pip install uptime-kuma-api

Alternately, you can install a specific version (e.g. 0.13.0):

pip install uptime-kuma-api==0.13.0

Then install the ansible collection itself:

ansible-galaxy collection install lucasheld.uptime_kuma

Alternately, you can install a specific version (e.g. 0.14.0):

ansible-galaxy collection install lucasheld.uptime_kuma:==0.14.0

Modules

The following modules are available:

• api_key
• api_key_info
• docker_host
• docker_host_info
• game_list_info
• login
• maintenance
• maintenance_info
• monitor
• monitor_info
• monitor_tag
• notification
• notification_info
• proxy
• proxy_info
• settings
• settings_info
• setup
• status_page
• status_page_info
• tag
• tag_info

Getting started

Directly after the installation of Uptime Kuma, the initial username and password must be set:

- name: Specify the initial username and password
  lucasheld.uptime_kuma.setup:
    api_url: http://127.0.0.1:3001
    api_username: admin
    api_password: secret123

For future requests you can either use these credentials directly or a token that must be generated once. The token usage is recommended because frequent logins lead to a rate limit. In this example we create a new monitor.

Option 1 (not recommended): Create a monitor by using the credentials directly:

- name: Login with credentials and create a monitor
  lucasheld.uptime_kuma.monitor:
    api_url: http://127.0.0.1:3001
    api_username: admin
    api_password: secret123
    name: Google
    type: http
    url: https://google.com
    state: present

Option 2 (recommended): Generate a token and create a monitor by using this token:

- name: Login with credentials once and register the result
  lucasheld.uptime_kuma.login:
    api_url: http://127.0.0.1:3001
    api_username: admin
    api_password: secret123
  register: result

- name: Extract the token from the result and set it as fact
  set_fact:
    api_token: "{{ result.token }}"

- name: Login by token and create a monitor
  lucasheld.uptime_kuma.monitor:
    api_url: http://127.0.0.1:3001
    api_token: "{{ api_token }}"
    name: Google
    type: http
    url: https://google.com
    state: present