Skip to content

Upgrade notes

Upgrade from v2.x.x to v3.x.x

Tip

When you're not using the API, or the Metrics exporters and you didn't configure any monitors via YAML, you don't need to do anything to upgrade to version 3.x.x!

YAML monitor config

The monitors property to define your monitors in your YAML configuration file has been renamed to http-monitors to better reflect its purpose. To make your existing file work with version 3.x.x, it's enough to just rename the property, no other changes are needed.

# v2.x.x
monitors:
- name: "My Monitor"
  url: "https://kuvasz-uptime.dev"
  uptime-check-interval: 60
  integrations:
    - "email:my-email-integration"
    - "slack:my-slack-integration"
# v3.x,x
http-monitors:
- name: "My Monitor"
# ...

API

/api/v1 endpoints will be supported for a limited time only, because a new version of the API has been introduced under /api/v2. Endpoints not explicitly listed below are expected to remain the same besides the path change, which means, that you can just replace /api/v1 with /api/v2 in your requests.

End of life of v1 endpoints

The v1 endpoints will be supported until 2025-12-31. After this date, they will be removed in the next feature release. Please make sure to migrate to the v2 endpoints before then. Please refer to the API documentation for more details.

Changed endpoints

  • GET /api/v2/settings: The response schema has changed compared to v1:

    • it doesn't return the integrations anymore (they're available under a separate endpoint now)
    • the MeterSettingsDto schema uses new property names for clarity: latestLatency -> httpLatestLatency, uptimeStatus -> httpUptimeStatus.
    • the editability of the monitors via the UI & the API is now reflected under editabilityState (readOnlyMode is gone)

Removed endpoints

The following endpoints have been removed/renamed in version 3.0.0:

  • GET /api/v1/health -> GET /api/v2/health: Everything remains the same, just the path has changed.

  • GET /api/v1/prometheus -> GET /api/v2/prometheus: Not just the path has changed, but also the gauge names are more scoped now. Please refer to the Metrics export section below for more details.

Metrics export

The provided gauges' names have changed to be more scoped. Here is a mapping of the old and new names (you need to update your Prometheus/OTLP configuration accordingly):

Old gauge name New gauge name
kuvasz.monitor.uptime.status kuvasz.http.uptime.status
kuvasz.monitor.latency.latest.milliseconds kuvasz.http.latency.latest.milliseconds
kuvasz.monitor.ssl.status kuvasz.http.ssl.status
kuvasz.monitor.ssl.expiry.seconds kuvasz.http.ssl.expiry.seconds
Old gauge name New gauge name
kuvasz_monitor_uptime_status kuvasz_http_uptime_status
kuvasz_monitor_latency_latest_milliseconds kuvasz_http_latency_latest_milliseconds
kuvasz_monitor_ssl_status kuvasz_http_ssl_status
kuvasz_monitor_ssl_expiry_seconds kuvasz_http_ssl_expiry_seconds

Configuration

Also, the following configuration properties changed as well, make sure to update your configuration accordingly:

Old property New property
metrics-exports.uptime-status metrics-export.http-uptime-status
metrics-exports.latest-latency metrics-export.http-latest-latency
Old variable New variable
ENABLE_UPTIME_STATUS_EXPORT ENABLE_HTTP_UPTIME_STATUS_EXPORT
ENABLE_LATEST_LATENCY_EXPORT ENABLE_HTTP_LATEST_LATENCY_EXPORT

Labels

The url label has been renamed to target on all gauges, to better reflect its purpose in a generic way.

Upgrading from v1.x.x to v2.x.x

If you're upgrading from Kuvasz v1 to Kuvasz v2, it's better if you just start with a fresh setup, except for the database (make sure that you do a backup of it), which should be backward compatible. Even if it's not a complete rewrite, a lot of things have changed under the hood, and the new version is not fully compatible with the old one.

All in all, you can use your old database, your data will be migrated automatically, but there are a few notable breaking changes you should be aware of:

  • Kuvasz is not distributed as a native (GraalVM based) Docker image anymore
  • The minimum required PostgreSQL version is now 12
  • The REST API is versioned now, and a few endpoints have been changed or removed. You can find the new API documentation here
  • Integrations are now configured via the YAML file, and the old, environment-variable-based configuration is no longer supported
  • The authentication and its configuration has been simplified, read the Authentication section carefully!

Warning

This list is not exhaustive, there might be other - minor - breaking changes that are not listed here.

Detailed upgrade notes (if necessary) for the future releases will be available in a dedicated section of the documentation.