Manage Software Updates with the Update Channel Service

Overview

The UpdateChannelService is a core component responsible for managing the platform's software update lifecycle. It determines the current update status, manages update channels, handles operator-initiated updates, and reconciles update history for automatic updates performed by other system components.

This service acts as a presentation and control layer for an in-VPC release-controller. Historically, this service performed its own network polls to an external update manifest endpoint. This model has been retired. The release-controller now owns the entire update process: polling for new releases, verifying their signatures, and applying them. The UpdateChannelService provides a stable API for operators by scraping the release-controller's /status endpoint, making it the single source of truth for update status presented in the administration interface.

This architectural change makes the update status reporting more robust and eliminates a class of false-positive errors, such as a "signature verification failed" status that could previously occur if a public key was not provisioned. This service performs no direct network calls to the external update platform and no signature verification.

Key responsibilities include:

• Resolving and caching the effective update status by querying the release-controller.
• Providing an API for operators to trigger "operator-approved" updates.
• Maintaining a durable s2r_update_history log of all updates, whether operator-initiated or automatic.
• Reconciling the update history on startup to account for out-of-band updates applied automatically by the release-controller.
• Managing per-administrator notifications for newly installed automatic updates.

How it Works

The service's functionality is divided into three main areas: status resolution, update application, and background reconciliation.

Update Status Resolution

The effective update status, visible to operators, is derived from the release-controller.

1. A call to retrieve status, such as via the GET /admin/v1/updates endpoint, invokes the effective() method.
2. This method uses a 30-second in-memory cache (CACHE_TTL) to reduce load.
3. If the cache is stale, resolveUncached() is called to compute a fresh status.
4. It fetches the current state from the in-VPC release-controller via the ReleaseControllerStatusClient. This client call is fail-open with a short timeout, preventing it from blocking or failing the status request.
5. The controller's health (ok, degraded) and its own product check results are translated into a calm, operator-facing status:
   • success: The controller is healthy and its last check was successful.
   • degraded: The controller is in a degraded state, or its last check for a product update failed.
   • unreachable: The release-controller could not be reached.
6. If the system is in operator_approved mode and the controller has observed a new version that has not yet been applied, the service exposes this version as latestAvailableVersion. In auto mode, this is always null because the controller applies updates automatically, so there is no "available-but-not-installed" state.
7. The service also attempts to close any in_progress operator-initiated updates by correlating them with terminal status reports from the controller (see Attempt-Based Correlation).
8. The final EffectiveStatus object is cached and returned.

Operator-Approved Updates

When the system's update_mode is set to operator_approved, an operator must manually trigger the application of an available update. This is handled by the applyUpdate method, exposed via POST /admin/v1/updates/apply.

1. An operator initiates the apply action, providing the target version.
2. The service immediately inserts a new row into the s2r_update_history table with a status of in_progress. This ensures a durable record of the attempt exists before any external side effects are initiated.
3. The service then calls ReleaseControllerStatusClient.triggerApply(), sending a signed request to the release-controller to begin the update.
4. The controller validates the request and begins the update process in the background, returning a 202 Accepted-style response quickly.
5. The UpdateChannelService handles the controller's response:
   • TRIGGERED: The request was accepted. The service updates the in_progress history row with the unique applyAttemptId returned by the controller. The row remains in_progress; its final state will be determined later via reconciliation.
   • Rejected (CONFLICT, UNAVAILABLE, etc.): The controller did not start the update. The service updates the pre-recorded in_progress row to a failed status (not_applied) with a reason based on the controller's feedback. This prevents dangling in_progress records for rollouts that never launched.

Startup and Background Reconciliation

The release-controller can apply updates automatically and out-of-band from the UpdateChannelService. The service includes reconciliation logic to ensure these updates are recorded and operators are notified.

Auto-Install Reconciliation

On application startup, reconcileAutoInstallOnStartup() runs to synchronize the history table with the current reality.

• It compares the platform's running version (currentVersion) against the to_version of the latest record in s2r_update_history.
• If the versions do not match, it indicates an out-of-band update occurred. The service inserts a new history record to bridge the gap, with initiated_by set to release-controller and status as success. This new record is flagged as an "unseen notification" for administrators.
• If the history table is empty (e.g., first boot), a baseline record is created.
• If the versions match, no action is taken.

Attempt-Based Correlation

A critical reconciliation task is closing out operator-initiated updates that were left in_progress. The service uses an attempt-based correlation mechanism.

• The release-controller maintains a list of recent terminal update attempts, each with a unique ID and a final status (success, rolled_back, failed).
• During status resolution and startup reconciliation, UpdateChannelService fetches these terminal attempts.
• For each terminal attempt reported by the controller, the service looks for an in_progress history row with a matching apply_attempt_id.
• If a match is found, the history row is updated to reflect the controller's final status, preserving the distinction between success, rolled_back, and other failures.
• This ensures that operator-initiated updates are reliably transitioned to a final state, even across service restarts or if multiple apply actions were triggered.

Update Flow Diagram

The following diagram illustrates the modern, controller-driven update flow. The UpdateChannelService no longer polls the external source directly; it queries the in-VPC Release Controller, which owns the update process.

flowchart TD
    subgraph "API Platform"
        A[Operator via Admin UI]
        B[UpdateChannelService]
        C[Release Controller]
    end
    D[External Update Source]

    A -- "1. Views update status" --> B
    B -- "2. Scrapes status from" --> C
    C -- "3. Periodically polls" --> D
    D -- "4. Provides release manifest" --> C
    C -- "5. Reports status to" --> B
    B -- "6. Displays status to" --> A

    A -- "7. Approves update" --> B
    B -- "8. Triggers apply on" --> C
    C -- "9. Fetches and applies update from" --> D

API Operations

The service exposes its functionality through several methods, which are typically surfaced via the administrative API.

Retrieving Effective Update Status

Provides a comprehensive snapshot of the current update status, configuration, and any available updates. This is the primary data source for the "Settings -> Updates" UI panel.

The response is a JSON object with the following fields:

Applying an Update

POST /admin/v1/updates/apply

Triggers the application of a specific software version. This is only used when the update_mode is operator_approved.

Request Body

A JSON object containing the target version. If the body is empty, the service will attempt to apply the latestAvailableVersion from the current status.

{
  "requestedVersion": "1.2.4"
}

Response Body

The response is a JSON object indicating the outcome of the trigger request.

• On success (TRIGGERED):

  {
    "fromVersion": "1.2.3",
    "toVersion": "1.2.4",
    "outcome": "TRIGGERED",
    "historyId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "in_progress",
    "note": "Apply requested — the release controller is applying 1.2.4 in the background. Watch history for the result."
  }
  

• On rejection (CONFLICT):

  {
    "fromVersion": "1.2.3",
    "toVersion": "1.2.5",
    "outcome": "CONFLICT",
    "historyId": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
    "status": "not_applied",
    "note": "The release controller could not apply 1.2.5 — it is not the currently observed available version, or automatic apply is not enabled on this install."
  }
  

Refreshing Update Status

POST /admin/v1/updates/check

Triggers an immediate, asynchronous refresh of the update status. This invalidates the in-memory cache and forces a fresh scrape of the release-controller's status. It does not perform any direct network poll to the external update platform.

Retrieving Update History

Retrieves a list of recent update events from the s2r_update_history table for the current installation. Each history row provides details about a specific version change.

The response is a list of HistoryRow objects.

Managing Notifications

These operations manage the per-administrator notifications that appear after an automatic update. An "unseen notification" is a history row initiated by the release-controller that a specific administrator has not yet acknowledged.

• notifications(adminSubject): Returns a count of unseen notifications and the most recent unseen HistoryRow for the given administrator.
• acknowledgeNotifications(adminSubject): Marks all unseen notifications for the given administrator as seen. This is an idempotent action that does not affect other administrators.

Configuration Reference

The UpdateChannelService is configured through system settings and Spring application properties (or environment variables).

Troubleshooting

| Condition / Outcome | Trigger | Meaning for Operator | --- | --- | | CONFLICT | POST /admin/v1/updates/apply | The release controller could not apply the requested version. This may be because it is not the currently observed available version, or because automatic apply is not enabled. | ALREADY_IN_PROGRESS | POST /admin/v1/updates/apply | An update is already being applied. The operator should monitor the update history for the result of the ongoing process. | NOT_OBSERVED | POST /admin/v1/updates/apply | No update is available to apply. The operator should trigger a status refresh (POST /admin/v1/updates/check) first. | UNAUTHORIZED | POST /admin/v1/updates/apply | The release controller rejected the apply request. This typically indicates a misconfiguration of the internal signing secret used for communication between services. | UNAVAILABLE | POST /admin/v1/updates/apply | Apply is not available. The in-VPC release controller is not reachable, or the internal signing secret is not set.

| FAILED | POST /admin/v1/updates/apply | The release controller could not verify the release to apply. The operator can try again. | --- | --- | | lastCheckStatus: degraded | GET /admin/v1/updates | The release-controller is reporting a non-healthy state, or it failed to check for a product update. The accompanying error message provides more detail. This is not a critical failure of the admin service itself. | lastCheckStatus: unreachable | GET /admin/v1/updates | The service could not communicate with the in-VPC release-controller. This is expected in deployments without a release-controller but indicates a problem otherwise.

See Also

• ReleaseControllerStatusClient: The client used to communicate with the in-VPC release-controller.
• SystemSettingRepository: The repository for retrieving system-wide configuration like update_mode and update_channel.
• UpdateChannelRepository: The repository for managing the s2r_update_history table.
• ProductIdentity: A component that provides the product identifier (e.g., s2r) used in constructing release notes URLs.

All SOAP-to-REST docs