Platform Update Service

Overview

The Update Channel Service manages the platform's update lifecycle. It provides the backend functionality for the administration UI's "Settings → Updates" panel, allowing operators to view the current version, check for updates, configure update behavior, and view installation history.

A key architectural aspect of this service is that it does not directly poll an external update platform for new releases. Instead, it acts as a client to an in-VPC release controller. The release controller is the sole component responsible for pulling, verifying, and applying new software versions. This service reflects the state reported by the release controller, providing a durable and consistent view of the update process.

The service is responsible for:

• Reporting the current platform version and update status.
• Managing update configuration, such as the update channel (release, beta, etc.) and update mode (auto or operator_approved).
• Providing a history of platform updates.
• Handling operator-initiated update approvals.
• Reconciling the update history on startup to account for automatic updates performed by the release controller.
• Managing notifications for automatically installed updates.

How It Works

The service's functionality is centered around reflecting the state of the release controller and managing a durable history of update events in the s2r_update_history table.

Status Reporting

The effective update status, as seen in the admin UI, is generated by the effective() method. This method uses a 30-second in-memory cache to reduce load. When the cache is invalid, it resolves the status by:

1. Reading operator-configured settings like update_channel and update_mode from the system settings repository.
2. Fetching the current status from the local release controller via its /status endpoint. This call is fail-open with a short timeout, ensuring the admin UI remains responsive even if the controller is absent or unhealthy.
3. Deriving a user-facing lastCheckStatus (success, degraded, unreachable) from the controller's reported health.
4. If the controller is in operator_approved mode and has observed a new version, this service surfaces it as latestAvailableVersion. In auto mode, the controller applies updates automatically, so no "available-but-not-installed" state exists.
5. Closing any in_progress update history rows if the controller's status now reports a terminal outcome (e.g., success, failed, rolled_back) for the corresponding update attempt. This correlation is done using a unique apply_attempt_id.

The following diagram illustrates the data flow for status reporting:

flowchart TD
    subgraph "API Platform"
        subgraph "Admin API"
            UCS["Update Service"]
        end
        subgraph "Release Controller"
            RC["Release Controller"]
        end
    end

    Operator["API Publisher (Operator)"] -- "1. Views update status" --> UCS
    UCS -- "2. GET /status" --> RC
    RC -- "3. Reports status" --> UCS
    UCS -- "4. Displays status to Operator" --> Operator

    RC -- "Pulls & verifies releases" --> UpdatePlatform["External Update Platform"]

Operator-Approved Updates

When the platform is in operator_approved update mode, an operator must explicitly trigger an available update. This is handled by the applyUpdate method, which is invoked via the POST /admin/v1/updates/apply endpoint.

The process is as follows:

1. The service first creates a new record in the s2r_update_history table with a status of in_progress. This ensures a durable record of the update attempt exists before any action is taken. A client-generated apply_attempt_id is included in this record for correlation.
2. It then sends a signed request to the release controller's triggerApply endpoint, passing the target version and the apply_attempt_id.
3. The release controller validates the request. If accepted, it begins the update process in the background and returns a TRIGGERED outcome.
4. The applyUpdate method receives the outcome:
   • If TRIGGERED, the history row remains in_progress. The final result will be determined later via status polling or startup reconciliation.
   • If the controller rejects the request (e.g., CONFLICT, NOT_OBSERVED), the service immediately updates the in_progress history row to a failed status, ensuring no dangling records exist for rollouts that never started.

Startup Reconciliation for Automatic Updates

The release controller can apply updates automatically without involving this service. To ensure the update history is accurate, a reconciliation process runs every time the application starts.

1. The service compares the current running version (currentVersion) against the to_version of the most recent record in the s2r_update_history table.
2. Attempt Correlation: Before comparing versions, it checks the release controller's status for any terminal outcomes of past update attempts. It closes any in_progress history rows that match a terminal apply_attempt_id reported by the controller. This ensures operator-initiated updates are correctly marked as success, failed, or rolled_back.
3. History Gap Detection: If the running version does not match the latest successful history record, it indicates an out-of-band update occurred.
4. The service inserts a new history record to represent this automatic update, with initiated_by set to release-controller. This new record appears as an unacknowledged notification for administrators in the UI.
5. On the very first boot of a new installation, a baseline history record is created.

Configuration

The update service is configured through a combination of system settings and environment variables.

System Settings

These settings are managed via the system settings API and control the update behavior.

Environment Variables & Application Properties

These properties configure service-level parameters.

API Reference

The service exposes functionality that backs several administrative API endpoints.

Get Effective Update Status

Retrieves the current update status, including channel, mode, current version, and any available updates. The response is cached for 30 seconds.

• Response Body (EffectiveStatus):

Apply an Update

Triggers the release controller to apply an update. This is intended for use in operator_approved mode.

• Endpoint: POST /admin/v1/updates/apply
• Request Body: An optional JSON body can specify the version to apply. If omitted, the service attempts to apply the latestAvailableVersion.
• Response: A JSON object detailing the outcome of the trigger request.

Example Response (Trigger Accepted)

If the release controller accepts the request, it returns a 202 status and begins the update in the background. The history row is left in_progress.

{
  "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."
}

Example Response (Trigger Rejected)

If the controller rejects the request, the response indicates the reason, and the pre-created history row is marked as not_applied.

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

Other Operations

The service also provides methods to support the following operations, typically exposed via the admin API:

• Get History: history(int limit) - Fetches a list of recent update history records for the current installation.
• Get Notifications: notifications(String adminSubject) - Fetches unseen auto-install notifications for a given administrator.
• Acknowledge Notifications: acknowledgeNotifications(String adminSubject) - Marks all unseen notifications as seen for a given administrator.
• Trigger Status Refresh: checkOnce(String trigger) - Immediately refreshes the cached status from the release controller. Backs the POST /admin/v1/updates/check endpoint.

Troubleshooting

| Issue | Cause & Meaning | "Last check status" is unreachable | The service could not connect to the in-VPC release controller. This is expected if the release controller is not deployed with your installation. The lastCheckError will be "The in-VPC release controller is not reachable." | "Last check status" is degraded | The release controller is running but reports a non-healthy state. This can mean the controller process itself is degraded, or that its own attempt to check for updates from the external platform failed. The lastCheckError will provide more detail, such as "The last update check could not verify a release from the update platform." | Update apply fails with CONFLICT | The release controller rejected the request because the target version is not the one it currently sees as available, or because automatic updates are not enabled for the installation. | Update apply fails with UNAUTHORIZED or UNAVAILABLE | The release controller rejected the request because an internal signing secret used for communication between this service and the controller is not configured correctly, or the controller is not reachable. | An update remains in_progress indefinitely | This can happen if an update was triggered but the platform was restarted before the release controller reported a terminal status. The status should resolve automatically during the next status check or application restart when the service reconciles its history with the controller's list of terminal attempts. If it persists, it may indicate an issue with the release controller itself. | installation_id is not configured error | An operation like applying an update or fetching history failed because the installation_id could not be resolved from system settings or the platform license. Ensure the installation_id setting is configured or a valid license is present.

All SOAP-to-REST docs