How openshift/cincinnati works
Project Overview and Main Purpose
• Cincinnati is an update protocol for facilitating automatic updates. It defines how transitions between release versions occur and provides a system for auto-updating clients.
• The README highlights two key executables – the “graph-builder” (which gathers metadata, builds the dependency/update graph, and talks to an upstream registry) and the “policy-engine” (which serves filtered/processed graph data over an HTTP API).
Main Components
a. Core Services:
• Graph-Builder Service: This component fetches image and release metadata from an upstream container registry (like Quay.io) and builds an update graph. It includes plugins (both internal and external) that perform tasks such as graph construction, filtering, and metadata enrichment.
• Policy-Engine Service: This service applies business rules or policies on the generated update graph and exposes a REST API endpoint (e.g., /graph?channel=…) for clients retrieving update paths.
• Client (or consumers): These are the systems or tools that query the policy-engine for update information.
b. Supporting Modules and Libraries:
• Cincinnati Core Library: Located mainly in the “cincinnati” directory, it defines the plugin interface (with a Protobuf schema for external plugins) and contains helper modules (like cincinnati/src/plugins) that are used by the various services.
• Commons Library: Offers shared configurations, error handling, metrics, and tracing setups.
• Additional Services: Other utilities (metadata-helper, policy-engine, prometheus-query, quay, rh-manifest-generator) that support the ecosystem either for metadata processing, manifest generation, or monitoring.
c. CI/CD and Deployment:
• The “dist” directory houses Dockerfiles, OpenShift configuration files, and deployment scripts. These contribute to build pipelines and deployment integration.
• The “.github” directory and associated scripts (in the “hack” directory) indicate CI/CD pipeline hooks and integration with external tooling.
Understanding Component Relationships and Data Flow
• Upstream Data: The system retrieves release metadata from an external registry (e.g., quay.io as defined by the environmental variables).
• Graph-Builder Process:
• Fetches metadata and applies various plugins (both “internal” and “external” as seen under cincinnati/src/plugins) to build the update graph.
• It may utilize several plugin modules (for example, channel filters, graph builders, release scrapers) to process and transform the data.
• Policy-Engine Process:
• Consumes the graph output (or a similar source) and applies policies (filtering based on channel, testing parameters) before exposing this data via an HTTP endpoint.
• Consumers (clients) then query the policy-engine, receiving data with details such as version, payload, and metadata.
Architectural Patterns & Design Principles
• Modular and Plugin-Based Architecture: The clear division into modules (graph building, policy checking, metadata fetching) and the use of plugins (both internal and external) means that the system is highly extensible.
• Service Decomposition: Two key executables (graph-builder and policy-engine) function as microservices, communicating via well-defined data formats.
• CI/CD Integration: The presence of Dockerfiles in the “dist” directory along with test directories (e2e and tests within graph-builder) suggests continuous integration practices and automated deployments.
• Declarative and Configurable: With many configuration options (e.g., environment variables and configuration files in “config” subdirectories), the system design supports configurable deployments and runtime behavior.