https://github.com/bkupidura/hass-simple-healthcheck

https://github.com/bkupidura/hass-simple-healthcheck

Last synced: 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/bkupidura/hass-simple-healthcheck
• Owner: bkupidura
• License: apache-2.0
• Created: 2021-11-02T19:43:45.000Z (about 3 years ago)
• Default Branch: main
• Last Pushed: 2023-10-08T22:29:31.000Z (over 1 year ago)
• Last Synced: 2024-10-11T14:14:38.196Z (3 months ago)
• Language: Python
• Size: 10.7 KB
• Stars: 6
• Watchers: 5
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: Readme.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# HomeAssistant Simple Healthcheck component

Currently HomeAssistant is not exposing healthcheck endpoint which can be used by K8s or docker.

This component tries to change that. It should be used only be people who really needs it, and understand how it works.

**This component will not ensure that yours HomeAssistant installation is really healthy.**

Initial discussion about HealthCheck endpoint was started [here](https://github.com/home-assistant/architecture/discussions/650).

Component was created for my K8s HomeAssistant deployment, but any comments or contribution is welcome!

## How it works

* Users need to create `simple_healthcheck_keepalive` automation

* Component creates new HTTP endpoint `/healthz`

* Component will subscribe to `simple_healthcheck_event`

* When event will be received entity `simple_healthcheck.last_seen` will be updated

* When `simple_healthcheck.last_seen` will not be updated for 60 seconds (by default), `/healthz` endpoint will return unhealthy state

### Fetching entity `simple_healthcheck.last_seen` state

Component can fetch last `simple_healthcheck.last_seen` state with two methods:

1. Fetch last state from `recorder` database (default behavior)

2. Fetch last state from `hass.states` directly

Fetching data from recorder database is prefered, as healthcheck will also confirm that `recorder` is working properly (in some aspect). Second method will be only used when `simple_healthcheck.last_seen` entity is excluded from recorder.

## Why `simple`?

HomeAssistant is complicated piece of software, containing multiple components/integrations.

This component checks only a few aspects of HomeAssistant health.

**WARNING: It is possible that HomeAssistant will not be able to perform some critical actions and still be reported as healthy.**

Currently component will confirm that:

* HomeAssistant HTTP server is working

* `simple_healthcheck_keepalive` automation is working

* HomeAssistant message bus is able to deliver `simple_healthcheck_event`

* HomeAssistant `recorder` is able to fetch `simple_healthcheck.last_seen` state

## Installation

Copy `simple_healthcheck` directory into `custom_components/` directory.

## Configuration

```

simple_healthcheck:

automation:

  - alias: 'simple_healthcheck_keepalive'

    trigger:

      - platform: time_pattern

        seconds: '/10'

    action:

      - event: simple_healthcheck_event

```

### Possible options

```

simple_healthcheck:

  auth_required: true

  threshold: 45

```

* auth_required - enable or disable authentication for `/healthz` endpoint (default: true)

* threshold - number of seconds to wait before marking as unhealthy (default: 60)

## HTTP endpoint `/healthz`

This component will create new HomeAssistant endpoint `/healthz`.

By default this endpoint requires HomeAssistant authentication with [long term token](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token).

### Healthy response

```

< HTTP/1.1 200 OK

< Content-Type: application/json

< Content-Length: 17

< Date: Tue, 02 Nov 2021 19:30:32 GMT

< Server: Python/3.9 aiohttp/3.7.4.post0

<

{"healthy": true}

```

### Unhealthy response

```

< HTTP/1.1 500 Internal Server Error

< Content-Type: application/json

< Content-Length: 18

< Date: Tue, 02 Nov 2021 19:30:31 GMT

< Server: Python/3.9 aiohttp/3.7.4.post0

<

{"healthy": false}

```