Upgrade Notification

[amorey]

Overview

We would like to add an "Upgrade Notification" feature to the Kubetail Dashboard that notifies users when a newer version of the Dashboard or the Kubetail API (Cluster API + Cluster Agent) is available and guides them toward an upgrade path appropriate for their environment. The goal is to improve user awareness of updates, reduce time spent on outdated versions, and increase adoption of critical fixes and new functionality.

Goals

• Detect whether the currently running version is behind the latest compatible release
• Communicate upgrade availability
• Provide actionable information that helps users understand what to upgrade to and how to do so
• Respect user context, including deployment mode, connectivity, and version constraints

Non-Goals

The Upgrade Notification feature does not perform upgrades automatically. Instead, it focuses on discovery, messaging, and user intent, leaving the actual upgrade execution to the user.

Design Overview

Runtime Environments

The dashboard can run either on the desktop (using the kubetail CLI tool) or in the cluster (using the kubetail-dashboard docker container). On the desktop, the dashboard allows users to switch between clusters which means it needs to be aware of the version of the Kubetail API running inside each cluster in addition to the version of the kubetail CLI tool itself. On the cluster, the dashboard only needs to be aware of the version of the services running inside its own namespace in the cluster.

Cluster Services Versioning

The "Kubetail API" consists of the Cluster API and the Cluster Agent and is typically deployed using the Kubetail Helm chart. Each helm release tracks its chart version number and while not every chart version bump will necessarily affect a given user's dashboard, we can simplify our version checks by treating the chart version of a given helm release as the single version number we can use for version checks.

Detection Mechanism

For both the CLI tool and the Helm chart we can use the GitHub releases API to obtain information about the latest available release:

• CLI tool - https://api.github.com/repos/kubetail-org/kubetail/releases/latest
• Helm chart - https://api.github.com/repos/kubetail-org/helm-charts/releases

For the Helm charts repo, every new release is treated as "latest" so we need to do our own parsing to identify the true "latest" available.

UX/UI

Detection frequency

• Run as a background-process on dashboard startup/access at most once every 12 hours

Notification Frequency

• First time it detects update → Shows banner
• If user closes banner → Don't show until 24 hours later
• If user does "Don't remind me" → Save in localStorage and don't show for that specific version

Timing

• Don't show immediately on load (can be annoying)
• Wait 3-5 seconds after the dashboard is ready

Visual Priority

• Informative banner (not red for error or yellow for warning)
• Add to notifications popup

Plan of Attack

We can split up this project into at least these PRs:

1. A PR to obtain the version of the Kubetail API running in each cluster in DesktopMode
2. A PR to obtain the self-version of the Helm release running in ClusterMode
3. A PR to display an Upgrade Notification when an upgrade is available

Problems and Solutions

1. How to guide the user to update based on their installation method?

   Problem: We cannot automatically detect if they used Homebrew, Snap, direct binary, etc.
   Solution: Remind the user to use their own package manager to perform the upgrade

2. How to handle network errors?

   Fail silently: (Do not show the banner if the GitHub API does not respond).

3. How to handle custom deployments without a Helm release chart version?

   We can assume custom deployments are also managing their own version bumps and ignore this for now

Open Questions

1. What information to show about the update?

Future Work

1. Differentiate between types of updates

   Examples:

    Critical: Security patches (urgent visual change)
    Recommended: Important bug fixes (normal banner)
    Optional: New features (less prominent)
   

2. Version conflict checks

   In DesktopMode, it would be helpful to perform version conflict checks to ensure that the client can send requests to a given Kubetail API instance

3. Update Channels

   Allow users to choose what type of releases to receive:

    Stable: Only stable versions (default)
    Beta: Include pre-releases
    LTS: Only long-term support versions
   

4. In-App Changelog

   Show complete changelog inside the dashboard (not just link to GitHub).
   Benefit: User doesn't need to open external browser to see what changed.

5. Push Notifications (Cluster)

   For admins who want to know immediately when there are security updates.

[DavidReque]

Detection Mechanism

Hybrid and decentralized detection system that queries the GitHub Releases API to obtain information about the latest available version, with verification performed on the backend and intelligent caching to minimize external calls.

1. Source: GitHub Releases API

https://api.github.com/repos/kubetail-org/kubetail/releases/latest

Reasons for this choice:

• Already your official source - Users already download from GitHub Releases
• No additional infrastructure - We don't need to maintain a separate version server
• Public and stable API - GitHub guarantees availability and reasonable rate limits (60 req/hour without auth, 5000 with token)

The API returns:

• tag_name: version (e.g., cli/v0.8.0)
• name: release name
• body: release notes (changelog)
• html_url: link to the release page
• published_at: publication date
• prerelease: whether it's pre-release or stable

Desktop Environment

Backend-Driven Detection with Frontend Banner

In the desktop environment, the Dashboard Backend embedded in the CLI will be responsible for checking if updates are available and exposing them to the frontend via GraphQL. The frontend will display a non-intrusive banner with update instructions.

Why This Option?

1. Desktop Mode Architecture

The flow in desktop is:

CLI Binary (kubetail)
    └─> Embeds Dashboard Backend (Go)
        └─> Serves Dashboard UI (static React)
            └─> User accesses via localhost:7500

The CLI already knows its own version (injected at compile-time in cmd.version), so the Backend can:

• Read the current CLI version from the parent process
• Query GitHub Releases API to get the latest version
• Compare and determine if an update is available

2. Backend is the Natural Place

• Already makes external queries (to Kubernetes API)
• Can cache results to avoid querying GitHub every time the dashboard is opened
• Handles network errors
• Exposes data via GraphQL that the frontend already consumes

Frontend should NOT do this verification because:

• It would duplicate logic that the backend cluster also needs
• Each browser tab would make its own request
• CORS can be an issue with GitHub API

3. Non-Intrusive UX

We will show a discreet banner at the top of the dashboard.

Banner characteristics:

• Only shown once per session (or until the user closes it)
• Does not block functionality
• Allows "snooze" to avoid annoyance
• Link to release notes on GitHub

4. Contextual Update Instructions

How to guide the user to update based on their installation method?

• Problem: We cannot automatically detect if they used Homebrew, Snap, direct binary, etc.
• Solution: Show instructions for ALL common methods in an informative modal

UX Considerations

Notification Frequency

• First time it detects update → Shows banner
• If user closes banner → Don't show until next restart of kubetail serve
• If user does "Don't remind me" → Save in localStorage and don't show for that specific version

Timing

• Don't show immediately on load (can be annoying)
• Wait 3-5 seconds after the dashboard is ready
• If the user is in the middle of a task (logs streaming), don't interrupt

Visual Priority

• Blue informative banner (not red for error or yellow for warning)
• Information icon
• Subtle fade-in animation

Cluster Environment

Dashboard Backend Queries Versions of All Components

In the cluster environment, the Dashboard Backend will check versions of ALL installed components (Dashboard, Cluster API, Cluster Agent) comparing them against the latest available on GitHub Releases.

Why This Option?

1. Component Architecture in Cluster

In cluster there are 3 independent services. Each can be at different versions, and all need to be updated in a coordinated manner.

2. The Dashboard Must Know ALL the State

The Dashboard is the visual "control plane," therefore it must:

• Know its own version
• Detect if Cluster API is installed and its version
• Detect if Cluster Agent is installed and its version
• Compare with latest available versions
• Show unified view of system state

3. Different Update Context

In cluster, the update is NOT done by the end user but by a cluster admin:

Typical update via Helm:

helm repo update
helm upgrade kubetail kubetail/kubetail -n kubetail-system

Or via YAML manifests:

kubectl apply -f https://github.com/.../kubetail-clusterauth.yaml

Open Questions

1. How often should it check for available updates?

• A) Only when starting the server/dashboard (1 time per session)
• B) Every X hours while running (e.g., every 12h)
• C) Once per day (first load of the day)

2. Persistence of "Dismiss"

If the user closes the banner, when should we show it again?

Options in Desktop:

• A) Show again on each new kubetail serve
• B) Save in localStorage: don't show until there's a NEWER version
• C) Option for "Don't remind me for this version" vs "Dismiss for now"

Options in Cluster:

Similar, but localStorage is per browser (not global for all admins)

3. How to handle installations without internet access?

• Fail silently: (Do not show the banner if the GitHub API does not respond).
• Add a configuration flag: to disable the feature entirely.
• Allow an alternative endpoint: (e.g., for self-hosted version info).

4. Differentiate between types of updates?

Examples:

• Critical: Security patches (urgent visual change)
• Recommended: Important bug fixes (normal banner)
• Optional: New features (less prominent)

5. What information to show about the update?

Future Work

1. Auto-Update (Desktop)

Automatic CLI update with a single click.

When to consider: If many users use manual binaries (not package managers)

2. Update Channels

Allow users to choose what type of releases to receive:

• Stable: Only stable versions (default)
• Beta: Include pre-releases
• LTS: Only long-term support versions

3. In-App Changelog

Show complete changelog inside the dashboard (not just link to GitHub).

Benefit: User doesn't need to open external browser to see what changed.

4. Push Notifications (Cluster)

For admins who want to know immediately when there are security updates.

5. Rollback Capability

Information on how to rollback if the update causes problems.