Skip to content

Latest commit

 

History

History
77 lines (54 loc) · 4.1 KB

protocol.md

File metadata and controls

77 lines (54 loc) · 4.1 KB
title parent nav_order
Cincinnati for Fedora CoreOS
Development
3

Cincinnati for Fedora CoreOS

Cincinnati is a protocol to provide "update hints" to clients, and it builds upon experiences with the Omaha update protocol. It describes a particular method for representing transitions between releases of a project, allowing clients to apply updates in the right order.

Update Graph

Cincinnati uses a directed acyclic graph (DAG) to represent the complete set of valid update-paths. Each node in the graph is a release (with payload details) and each directed edge is a valid transition.

Clients

Cincinnati clients are the final consumers of the update graph and payloads. A client periodically queries the Cincinnati service in order to fetch updates hints. Once it discovers at least a valid update edge, it may or may not decide to apply it locally (based on its configuration and heuristic).

Graph API

Request

HTTP GET requests are used to fetch the DAG (as a JSON object) from the Graph API endpoint. Requests SHOULD be sent to the Graph API endpoint at /v1/graph and MUST include the following header:

Accept: application/json

Fedora CoreOS clients MUST provide additional details as URL query parameters in the request.

Key Optional Description
basearch required base architecture (non-empty string)
stream required client-selected update stream (non-empty string)
node_uuid optional application-specific unique-identifier for the client
os_version optional current OS version
os_checksum optional current OS checksum
group optional update group
rollout_wariness optional client wariness to update rollout
platform optional client platform

Response

A positive response to the /v1/graph endpoint MUST be a JSON representation of the update graph. Each known release is represented by an entry in the top-level nodes array. Each of these entries includes the release version label, a payload identifier and any additional metadata. Each entry follows this schema:

Key Optional Description
version required the version of the release, as a unique (across "nodes" array) non-empty JSON string
payload required payload identifier, as a JSON string
metadata required a string->string map conveying arbitrary information about the release

Allowed transitions between releases are represented as a top-level edges array, where each entry is an array-tuple. Each of these tuples has two fields: the index of the starting node, and the index of the target node. Both are non-negative integers, ranging from 0 to len(nodes)-1.

For an example of a valid JSON document from a graph response, see response.json.

Errors

Errors on the /v1/graph endpoint SHOULD be returned to the client as JSON objects, with a 4xx or 5xx HTTP status code. Error values carry a type-identifier and a textual description, according to the following schema:

Key Optional Description
kind required error type identifier, as a non-empty JSON string
value required human-friendly error description, as a non-empty JSON string