Skip to content

NO-JIRA: Add UBIQUITOUS_LANGUAGE.md #533

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

Open
mdbooth wants to merge 1 commit into
base: main
Choose a base branch
from
Open

NO-JIRA: Add UBIQUITOUS_LANGUAGE.md #533

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
128 changes: 128 additions & 0 deletions UBIQUITOUS_LANGUAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# Ubiquitous Language

## APIs & Namespaces

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Machine API** | OpenShift's native machine management API for provisioning and managing compute instances | MAPI (in user-facing text) |
| **Cluster API** | Upstream Kubernetes SIG project providing declarative machine lifecycle management | CAPI (in user-facing text) |
| **MAPI Namespace** | The `openshift-machine-api` namespace where Machine API resources live | |
| **CAPI Namespace** | The `openshift-cluster-api` namespace where Cluster API resources live | |
| **Operator Namespace** | The `openshift-cluster-api-operator` namespace where the operator itself is deployed | |

## Machine Resources

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Instance** | The actual cloud compute resource (e.g. an EC2 instance, an Azure VM) that a MAPI Machine or Infrastructure Machine represents | VM, server, host |
| **MAPI Machine** | A Machine API resource representing an Instance; contains both generic and platform-specific configuration in a single object | unqualified "Machine" |
| **CAPI Machine** | A Cluster API resource representing the generic aspects of an Instance; references a separate Infrastructure Machine for platform-specific configuration | unqualified "Machine" |
| **MAPI MachineSet** | A Machine API set of identically-configured MAPI Machines with a desired replica count | unqualified "MachineSet" |
| **CAPI MachineSet** | A Cluster API set of identically-configured CAPI Machines with a desired replica count; references an Infrastructure Template | unqualified "MachineSet" |
| **Infrastructure Machine** | A CAPI platform-specific resource (e.g. AWSMachine, AzureMachine) representing the Instance backing a CAPI Machine. Commonly abbreviated to **InfraMachine** | provider machine |
| **Infrastructure Template** | A platform-specific template (e.g. AWSMachineTemplate) used by a CAPI MachineSet to stamp out new Infrastructure Machines. Commonly abbreviated to **InfraTemplate** | MachineTemplate (ambiguous) |

## Cluster Resources

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Core Cluster** | The Cluster API Cluster resource representing the OpenShift cluster itself | CAPI Cluster |
| **Infrastructure Cluster** | A platform-specific cluster resource (e.g. AWSCluster) representing the cloud infrastructure state of the cluster. Commonly abbreviated to **InfraCluster** | |
| **Infrastructure** | The OpenShift `config.openshift.io/v1` singleton resource that identifies the cluster's platform type | Infra (ambiguous with Infrastructure Cluster) |

## Providers

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Core Provider** | A CAPI Operator resource representing the core Cluster API controller components | |
| **Infrastructure Provider** | A platform-specific project (e.g. CAPA for AWS, CAPZ for Azure) consisting of cloud-specific CRDs and controllers that operate on them; installed by the CAPI Operator using manifests from the Infrastructure Provider's container image | Cloud provider (ambiguous), unqualified "provider" |
| **Platform** | The specific cloud or infrastructure backend (AWS, Azure, GCP, vSphere, OpenStack, PowerVS, Bare Metal) | Provider (ambiguous with Infrastructure Provider) |

## Authority & Migration

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Authoritative API** | The API (Machine API or Cluster API) that currently owns and is the source of truth for a given resource | Owner, primary, active API |
| **Non-Authoritative** | The mirrored copy of a resource managed by the API that is not currently authoritative | Secondary, replica, shadow |
| **Migration** | The process of transferring authoritative control of a resource from one API to the other | Handover (acceptable synonym), switchover, cutover |
| **Migrating** | The transitional AuthoritativeAPI state during which control is being transferred between APIs | |

## Synchronization

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Synchronization** | The mechanism that keeps the authoritative and non-authoritative copies of a resource consistent | Sync (acceptable shorthand in code), replication, mirroring |
| **Synchronized Condition** | A status condition on a MAPI resource indicating whether **Synchronization** of its non-authoritative copy is current | Sync status |
| **Synchronized Generation** | The metadata generation at which a resource was last successfully synchronized | Sync generation |
| **Sync Finalizer** | A finalizer (`sync.machine.openshift.io/finalizer`) preventing premature deletion of non-authoritative resources | |

## Pausing

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Paused** | A state where a CAPI resource's reconciler stops processing it, controlled by the `cluster.x-k8s.io/paused` annotation | Frozen, suspended, disabled |
| **Paused Annotation** | The `cluster.x-k8s.io/paused` annotation whose presence requests a CAPI controller to stop reconciling a resource | |
Comment on lines +63 to +64
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Pausing semantics are internally inconsistent across APIs.

Line 63 defines Paused as a CAPI-only behavior, but Line 100/Line 111 imply the “old authority” is always paused during migration. That reads as if MAPI resources can also be paused the same way, which conflicts with the glossary definition.

Suggested wording adjustment 
-- During **Migration**, the old authority is **Paused** to prevent conflicting reconciliation
+- During **Migration**, if the old authority is a CAPI resource, it is **Paused** to prevent conflicting reconciliation; for MAPI authority, use explicit controller handoff semantics instead of CAPI pause terminology
-- **Domain expert:** "Both controllers are always running. The migration controller sets the status to **Migrating**, then requests the old **Authoritative API**'s resource to be **Paused**. It waits for the **Paused Condition** to confirm the old controller has stopped reconciling that specific resource, so only one controller is operating on any given **Instance** at a time."
+- **Domain expert:** "Both controllers are always running. The migration controller sets the status to **Migrating**. When the old authority is CAPI, it requests that resource to be **Paused** and waits for the **Paused Condition**; otherwise it uses the API-specific handoff path. This ensures only one controller operates on any given **Instance** at a time."

Also applies to: 100-100, 111-111

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@UBIQUITOUS_LANGUAGE.md` around lines 63 - 64, The glossary entry "Paused" and
"Paused Annotation" currently describe pause as a CAPI-only reconciler behavior
tied to the cluster.x-k8s.io/paused annotation; update the other mentions that
refer to the "old authority" during migration to explicitly state that pause
semantics apply only to CAPI controllers/resources (not MAPI resources) or that
the migration process treats CAPI-managed resources as paused by CAPI
controllers, clarifying that MAPI resources are not paused by the same
annotation; locate and edit the instances referencing "old authority" and
"migration" to use this explicit phrasing and reference the
cluster.x-k8s.io/paused annotation and the "Paused" glossary term for
consistency.

| **Paused Condition** | A status condition set by CAPI reconcilers confirming the resource is paused | |

## Conversion

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Conversion** | The bidirectional transformation of resource specs and statuses between Machine API and Cluster API representations | Translation, mapping, transformation |
| **MAPI-to-CAPI Conversion** | Conversion direction from MAPI Machines or MAPI MachineSets to their CAPI equivalents plus Infrastructure Machines or Infrastructure Templates | |
| **CAPI-to-MAPI Conversion** | Conversion direction from CAPI Machines or CAPI MachineSets plus their Infrastructure Machines or Infrastructure Templates back to MAPI equivalents | |

## Machine Lifecycle

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **Phase** | A Machine API status field indicating the machine's lifecycle stage (Provisioning, Running, Deleting) | State (ambiguous) |
| **Node Ref** | A reference from a MAPI Machine or CAPI Machine to the Kubernetes Node object it backs | |
| **Readiness Gate** | A custom condition that must be true before a CAPI Machine is considered ready | |
| **Externally Managed** | An Infrastructure Cluster marked with `cluster.x-k8s.io/managed-by` indicating no **Infrastructure Provider** reconciles it | |

## Operator Status

| Term | Definition | Aliases to avoid |
| --- | --- | --- |
| **ClusterOperator** | An OpenShift resource tracking the operator's overall health via Available, Progressing, and Degraded conditions | Operator status |

## Relationships

- A **MAPI Machine** and a **CAPI Machine** exist as parallel resources linked by **Synchronization**, both representing the same **Instance**
- Exactly one of the two copies is the **Authoritative API** at any time; the other is **Non-Authoritative**
- A **MAPI MachineSet** owns zero or more **MAPI Machines**
- A **CAPI MachineSet** owns zero or more **CAPI Machines** and references an **Infrastructure Template**
- Each **CAPI Machine** references exactly one **Infrastructure Machine** via `InfrastructureRef`; a **MAPI Machine** contains its platform-specific configuration inline
- The **Core Cluster** references exactly one **Infrastructure Cluster** via `InfrastructureRef`
- An **Infrastructure Provider** manages the lifecycle of **Infrastructure Machines** and **Infrastructure Clusters** for a given **Platform**
- **Migration** transitions the **Authoritative API** from one API to the other, passing through the **Migrating** state
- During **Migration**, the old authority is **Paused** to prevent conflicting reconciliation
- **Conversion** is used by **Synchronization** to translate resources between the two API representations

## Example dialogue

> **Dev:** "When a user wants to move a MAPI Machine to Cluster API, what happens?"
>
> **Domain expert:** "They set `Spec.AuthoritativeAPI` to Cluster API on the **MAPI Machine**. The migration controller detects the mismatch with `Status.AuthoritativeAPI` and begins a **Migration**."
>
> **Dev:** "So both controllers are running during Migration?"
>
> **Domain expert:** "Both controllers are always running. The migration controller sets the status to **Migrating**, then requests the old **Authoritative API**'s resource to be **Paused**. It waits for the **Paused Condition** to confirm the old controller has stopped reconciling that specific resource, so only one controller is operating on any given **Instance** at a time."
>
> **Dev:** "And the Non-Authoritative copy -- is it just a mirror?"
>
> **Domain expert:** "Exactly. The sync controller performs **Conversion** from the **Authoritative** copy and updates the **Non-Authoritative** one. It tracks this via the **Synchronized Condition** and **Synchronized Generation** so we know when they've diverged."
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Use canonical glossary term to avoid reintroducing ambiguity.

Line 115 says “Authoritative copy”, but the defined term is Authoritative API (and Non-Authoritative). Prefer the exact glossary term for consistency.

Suggested edit 
-- > **Domain expert:** "Exactly. The sync controller performs **Conversion** from the **Authoritative** copy and updates the **Non-Authoritative** one. It tracks this via the **Synchronized Condition** and **Synchronized Generation** so we know when they've diverged."
+- > **Domain expert:** "Exactly. The sync controller performs **Conversion** from the copy managed by the **Authoritative API** and updates the **Non-Authoritative** one. It tracks this via the **Synchronized Condition** and **Synchronized Generation** so we know when they've diverged."
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
> **Domain expert:** "Exactly. The sync controller performs **Conversion** from the **Authoritative** copy and updates the **Non-Authoritative** one. It tracks this via the **Synchronized Condition** and **Synchronized Generation** so we know when they've diverged."
> **Domain expert:** "Exactly. The sync controller performs **Conversion** from the copy managed by the **Authoritative API** and updates the **Non-Authoritative** one. It tracks this via the **Synchronized Condition** and **Synchronized Generation** so we know when they've diverged."
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@UBIQUITOUS_LANGUAGE.md` at line 115, Replace the phrase "Authoritative copy"
with the canonical glossary term "Authoritative API" in the sentence quoted (the
line containing the sync controller description), so it reads consistently with
the defined terms (Authoritative API and Non-Authoritative) and avoids
reintroducing ambiguity about the copy vs API wording.

>
> **Dev:** "What about the Infrastructure Machine? Does it get duplicated too?"
>
> **Domain expert:** "A **MAPI Machine** doesn't have a separate **Infrastructure Machine** -- it contains the platform-specific configuration inline in a single object. A **CAPI Machine** splits that out into a separate **Infrastructure Machine** resource. During **Conversion**, the sync controller extracts the platform-specific parts of the **MAPI Machine** into the **Infrastructure Machine**, or merges them back the other way. The **Sync Finalizer** prevents the **Infrastructure Machine** from being deleted before both sides are cleaned up."

## Flagged ambiguities

- **"Provider"** is used to mean both the cloud platform (AWS, Azure) and the platform-specific project (**Infrastructure Provider**). Use **Platform** for the cloud backend and **Infrastructure Provider** for the project and its CRDs and controllers.
- **"Infrastructure"/"Infra"** is overloaded across three concepts: the OpenShift **Infrastructure** singleton (platform detection), **Infrastructure Cluster** (cloud cluster state), and **Infrastructure Machine** (cloud instance). Always use the full compound term.
- **"Template"** can refer to either a CAPI MachineSet's machine template spec or the platform-specific **Infrastructure Template** resource. Use **Infrastructure Template** for the platform-specific resource.
- **"Sync"** is acceptable in code identifiers but user-facing text should use **Synchronization** to avoid ambiguity with other sync concepts (e.g. secret sync, which is a separate controller syncing secrets between namespaces, not machine state).
- **"Machine"/"MachineSet"** without a qualifier is ambiguous — both APIs define these resources with different structures. Always qualify as **MAPI Machine**/**CAPI Machine** and **MAPI MachineSet**/**CAPI MachineSet**.
- **"MAPI"/"CAPI"** are acceptable in code and internal identifiers but user-facing text (logs, errors, docs) should use **Machine API** and **Cluster API** per project convention.