Link Search Menu Expand Document

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.

KeyOptionalDescription
basearchrequiredbase architecture (non-empty string)
streamrequiredclient-selected update stream (non-empty string)
node_uuidoptionalapplication-specific unique-identifier for the client
os_versionoptionalcurrent OS version
os_checksumoptionalcurrent OS checksum
groupoptionalupdate group
rollout_warinessoptionalclient wariness to update rollout
platformoptionalclient 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:

KeyOptionalDescription
versionrequiredthe version of the release, as a unique (across “nodes” array) non-empty JSON string
payloadrequiredpayload identifier, as a JSON string
metadatarequireda 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:

KeyOptionalDescription
kindrequirederror type identifier, as a non-empty JSON string
valuerequiredhuman-friendly error description, as a non-empty JSON string