diff --git a/hyperfleet/docs/glossary.md b/hyperfleet/docs/glossary.md index 87c03d1d..e8d77793 100644 --- a/hyperfleet/docs/glossary.md +++ b/hyperfleet/docs/glossary.md @@ -1,7 +1,7 @@ --- Status: Active Owner: HyperFleet Architecture Team -Last Updated: 2026-08-17 +Last Updated: 2026-08-26 --- # HyperFleet Glossary @@ -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 | diff --git a/hyperfleet/standards/ticket-hygiene.md b/hyperfleet/standards/ticket-hygiene.md index a2c16b05..02acb795 100644 --- a/hyperfleet/standards/ticket-hygiene.md +++ b/hyperfleet/standards/ticket-hygiene.md @@ -1,7 +1,7 @@ --- Status: Active Owner: HyperFleet Platform Team -Last Updated: 2026-05-20 +Last Updated: 2026-08-26 --- # HyperFleet Ticket Hygiene Standard @@ -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. ---