Skip to content

HYPERFLEET-1599: Add Applier/Operator components and combining rule #209

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openshift-merge-bot merged 1 commit into from
Aug 27, 2026
Merged

HYPERFLEET-1599: Add Applier/Operator components and combining rule #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion hyperfleet/docs/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
Status: Active
Owner: HyperFleet Architecture Team
Last Updated: 2026-08-17
Last Updated: 2026-08-26
---

# HyperFleet Glossary
Expand Down Expand Up @@ -31,10 +31,12 @@ Definitions for HyperFleet-specific terms, concepts, and abbreviations used acro
| **CloudEvent** | A message conforming to the [CloudEvents 1.0 specification](https://cloudevents.io/), used as the event format for all messages published by Sentinel and consumed by Adapters. HyperFleet CloudEvents use the type `com.redhat.hyperfleet.cluster.reconcile.v1` and carry a minimal payload (anemic event pattern). | Broker, Sentinel, Adapter Framework |
| **Cluster** | The primary resource managed by HyperFleet. A cluster represents a HyperShift-managed OpenShift cluster. Clusters have a spec (desired state) and a status (current state aggregated from adapter reports). Referred to as `/clusters` in the API. | API, Sentinel, Adapter Framework |
| **Condition** | A structured status field following the Kubernetes conditions pattern. Each adapter reports three standard conditions per resource: `Available`, `Applied`, and `Health`. Conditions include a `type`, `status` (True/False/Unknown), `reason`, and `message`. In GET responses, the API adds `last_transition_time` (API-managed). See: [Status Guide](status-guide.md) | Adapter Framework, Sentinel, API |
| **Cross-Cutting Component** | A ticket component identifying the kind of artifact the work produces regardless of which system it touches (Architecture, CICD, Claude Plugins, Documentation, E2E Tests, OCI). Combined with a domain component when the ticket's primary output is that artifact rather than working code. See: [Ticket Hygiene → Valid Components](../standards/ticket-hygiene.md#valid-components) | All |
| **Dead Letter Queue (DLQ)** | A message broker queue that receives messages that could not be processed after the maximum number of retries. HyperFleet uses DLQs (where supported by the broker) to surface persistently failing events for manual inspection and alerting. | Broker |
| **Decision Logic** | The CEL-based configuration in a Sentinel instance that determines when to publish a reconciliation event. Composed of named `params` (intermediate boolean expressions) and a `result` (boolean CEL expression combining the params). Defined in the Sentinel's `broker.yaml` / ConfigMap under `message_decision`. | Sentinel |
| **Desire** | A declaration of intent targeting a single Kubernetes resource on a management cluster, written by an adapter to the desire store and reconciled by the Applier. Three types: **ApplyDesire** (create/update the resource via server-side apply), **DeleteDesire** (delete it), and **ReadDesire** (mirror its live state back to the control plane). Identity: `(managementCluster, type, group, resource, namespace, name)`. See: [Desire Identity Spike](spike-desire-identity-ownership.md) | Adapter Framework, Applier |
| **Desire Store** | A rebuildable delivery channel (replacing Maestro/ManifestWork for remote clusters) that transports desires (ApplyDesire, DeleteDesire, ReadDesire) from an Adapter to an Applier. Not a source of truth — if lost, the Adapter recomputes and rewrites desires from API state. See: [Desire Identity Spike](spike-desire-identity-ownership.md), [SPIKE: Evaluate Running the Desire Store on the API Postgres](desire-store-api-postgres-spike.md) | Adapter Framework, API, Applier |
| **Domain Component** | A ticket component identifying which HyperFleet system the work lives in (Adapter, API, Applier, Infra, Message Broker, Operator, Sentinel). Most tickets have exactly one; two domain components should not be combined on a single ticket. See: [Ticket Hygiene → Valid Components](../standards/ticket-hygiene.md#valid-components) | All |
| **Enrichment Table** | A database table storing tenant identity as key/value pairs per resource (e.g., `org=acme-corp`, `project=platform`). One value per key per resource. Server-owned and immutable after resource creation. See: [Multi-Tenant Identity and Authorization Design](multi-tenant-identity-authz-design.md) | API |
| **Event** | See CloudEvent (below). | Broker, Sentinel, Adapter Framework |
| **Envoy** | The API ingress proxy in HyperFleet. All API traffic, external and internal, passes through Envoy; no other route to the API is permitted. Strips client-supplied identity and tenant headers before forwarding to Authorino for authorization. See: [ADR-0020](../adrs/0020-envoy-authorino-api-gateway.md) | API, Sentinel, Adapter Framework |
Expand Down
23 changes: 17 additions & 6 deletions hyperfleet/standards/ticket-hygiene.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
Status: Active
Owner: HyperFleet Platform Team
Last Updated: 2026-05-20
Last Updated: 2026-08-26
---

# HyperFleet Ticket Hygiene Standard
Expand Down Expand Up @@ -100,23 +100,34 @@ Epics MUST include in their description:

## Valid Components

Each ticket MUST have at least one component assigned. Use the component that best matches the primary area of work.
Each ticket MUST have at least one component assigned. Components fall into two kinds: **domain** components (which system the work lives in) and **cross-cutting** components (which kind of work it is, regardless of system). Use the component(s) that best match the work — see [Combining Components](#combining-components) below.

### Domain Components

| Component | Scope | Repository |
|-----------|-------|------------|
| Adapter | Adapter framework, task configs, resource lifecycle | [hyperfleet-adapter](https://github.com/openshift-hyperfleet/hyperfleet-adapter) |
| API | REST API service, handlers, DAOs, middleware | [hyperfleet-api](https://github.com/openshift-hyperfleet/hyperfleet-api) |
| Applier | Desire store backends, applier controllers, remote applier connectivity | [hyperfleet-applier](https://github.com/openshift-hyperfleet/hyperfleet-applier) |
| Infra | Helm umbrella charts, Terraform modules, deployment scripts | [hyperfleet-infra](https://github.com/openshift-hyperfleet/hyperfleet-infra) |
| Message Broker | Shared broker library (Pub/Sub, RabbitMQ, CloudEvents) | [hyperfleet-broker](https://github.com/openshift-hyperfleet/hyperfleet-broker) |
| Operator | Bundle controller, HyperFleetConfig CRD, OLM packaging, operator lifecycle | [hyperfleet-operator](https://github.com/openshift-hyperfleet/hyperfleet-operator) |
| Sentinel | Sentinel reconciliation service, decision engine | [hyperfleet-sentinel](https://github.com/openshift-hyperfleet/hyperfleet-sentinel) |

### Cross-Cutting Components

| Component | Scope | Repository |
|-----------|-------|------------|
| Architecture | Architecture docs, standards, ADRs, working agreements | [architecture](https://github.com/openshift-hyperfleet/architecture) |
| CICD | Prow jobs, Konflux pipelines, release automation | Multiple repos (CI config) |
| Claude Plugins | Claude Code plugins, skills, and AI-assisted tooling | [hyperfleet-claude-plugins](https://github.com/openshift-hyperfleet/hyperfleet-claude-plugins) |
| Documentation | Developer guides, authoring guides, reference docs, pattern docs | Multiple repos |
| E2E Tests | End-to-end test suites and test infrastructure | [hyperfleet-e2e](https://github.com/openshift-hyperfleet/hyperfleet-e2e) |
| Infra | Operator, Helm umbrella charts, deployment scripts | [hyperfleet-infra](https://github.com/openshift-hyperfleet/hyperfleet-infra) |
| Message Broker | Shared broker library (Pub/Sub, RabbitMQ, CloudEvents) | [hyperfleet-broker](https://github.com/openshift-hyperfleet/hyperfleet-broker) |
| OCI | OCI artifact distribution, Helm chart publishing | Multiple repos |
| Sentinel | Sentinel reconciliation service, decision engine | [hyperfleet-sentinel](https://github.com/openshift-hyperfleet/hyperfleet-sentinel) |

> **Note:** If a ticket spans multiple components, assign the primary component. Add secondary components only when the work equally affects both areas.
### Combining Components

Most tickets need exactly one domain component. Add a cross-cutting component alongside it when the ticket's primary output is that kind of artifact rather than working code — for example, a design spike that lives in the Applier domain gets `Applier` + `Architecture`; a guide documenting the Operator's CR contract gets `Operator` + `Documentation`. Don't combine two domain components — if a ticket genuinely spans two systems (e.g. Adapter and Applier), split it or pick the domain where most of the work lands.

---

Expand Down