HYPERFLEET-1409 - feat: report status conditions on HyperFleetConfig

api/v1alpha1/hyperfleetconfig_types.go

@@ -84,8 +84,7 @@ var AllSizingProfiles = []SizingProfile{SizingProfileSmall, SizingProfileMedium,
 // operator-layer vocabulary describing installation health, and is distinct from
 // the HyperFleet API's own resource-condition vocabulary (Available/Ready/
 // Reconciled/LastKnownReconciled/per-adapter; see architecture ADR-0007 and
-// ADR-0008). The bundle controller (HYPERFLEET-1409) populates these; this story
-// defines the schema only.
+// ADR-0008). Populated by the bundle controller as of HYPERFLEET-1409.
 const (
 	// ConditionAvailable is True when the installed operand (the API) is
 	// deployed and healthy.
@@ -98,16 +97,50 @@ const (
 	ConditionDegraded = "Degraded"
 )
 
+// Reason strings for the operator-layer conditions above (HYPERFLEET-1409).
+// These are published API vocabulary — partners may read status.conditions[].reason
+// — so every writer of a condition must use one of these constants rather than an
+// ad hoc string, and the set must stay documented in docs/status-conditions.md.
+const (
+	// ReasonDeploymentAvailable: Available=True — the operand Deployment reports
+	// Available and all desired replicas are ready.
+	ReasonDeploymentAvailable = "DeploymentAvailable"
+	// ReasonDeploymentUnavailable: Available=False — the operand Deployment is
+	// missing or has zero available replicas.
+	ReasonDeploymentUnavailable = "DeploymentUnavailable"
+	// ReasonDeploymentNotReady: Available=False — the operand Deployment exists
+	// with some, but not all, replicas ready.
+	ReasonDeploymentNotReady = "DeploymentNotReady"
+	// ReasonRolloutInProgress: Progressing=True — the operand Deployment has not
+	// finished rolling out its current generation.
+	ReasonRolloutInProgress = "RolloutInProgress"
+	// ReasonRolloutComplete: Progressing=False — the operand Deployment is fully
+	// rolled out and stable.
+	ReasonRolloutComplete = "RolloutComplete"
+	// ReasonAsExpected: Degraded=False — no failure signal (ClusterOperator
+	// convention default).
+	ReasonAsExpected = "AsExpected"
+	// ReasonReferencedSecretMissing: Degraded=True — a Secret referenced by the
+	// spec (database, TLS, or JWKS) does not exist in the operator's namespace.
+	ReasonReferencedSecretMissing = "ReferencedSecretMissing"
+	// ReasonReconcileError: Degraded=True — a component failed to render or
+	// apply, or JWKS discovery failed with no cached fallback available, during
+	// the most recent reconcile.
+	ReasonReconcileError = "ReconcileError"
+)
+
 // SecretReference references a Secret by name. Referenced Secrets must live in
 // the operator's own namespace: because HyperFleetConfig is cluster-scoped, no
 // namespace field is exposed (name-only + operator-namespace convention, decided
 // in the HYPERFLEET-1406 API review).
 //
-// TODO(HYPERFLEET-1512): the operator-namespace constraint is convention-only
-// today — the schema cannot enforce it (CEL sees no cross-object/namespace
-// state; ADR-0019 rules out webhooks). The reconciler must enforce it (resolve
-// the Secret in the operator's own namespace and surface a Degraded condition
-// when it is missing) once it lands.
+// The operator-namespace constraint is convention-only at the schema level —
+// CEL sees no cross-object/namespace state, and ADR-0019 rules out webhooks —
+// but the reconciler does resolve every reference in its own namespace
+// (referencedSecretData) and surfaces ConditionDegraded /
+// ReasonReferencedSecretMissing when one is absent (HYPERFLEET-1409).
+// TODO(HYPERFLEET-1512): decide whether any further enforcement (e.g. rejecting
+// reconciliation outright) belongs here.
 type SecretReference struct {
 	// name is the name of the Secret in the operator's namespace. It must be a
 	// valid DNS-1123 subdomain, matching what k8s.io/apimachinery/pkg/util/validation
@@ -255,8 +288,9 @@ type HyperFleetConfigSpec struct {
 }
 
 // HyperFleetConfigStatus defines the observed state of HyperFleetConfig. It is
-// populated by the bundle controller in later stories; this story defines the
-// schema only.
+// populated by the bundle controller after every reconcile (HYPERFLEET-1409),
+// rolling up each component's health into the Available/Progressing/Degraded
+// conditions.
 type HyperFleetConfigStatus struct {
 	// observedGeneration is the .metadata.generation the operator last acted on.
 	//
@@ -280,6 +314,8 @@ type HyperFleetConfigStatus struct {
 // +kubebuilder:printcolumn:name="Bundle",type=string,JSONPath=`.spec.bundle`
 // +kubebuilder:printcolumn:name="Profile",type=string,JSONPath=`.spec.api.profile`
 // +kubebuilder:printcolumn:name="Available",type=string,JSONPath=`.status.conditions[?(@.type=="Available")].status`
+// +kubebuilder:printcolumn:name="Progressing",type=string,JSONPath=`.status.conditions[?(@.type=="Progressing")].status`
+// +kubebuilder:printcolumn:name="Degraded",type=string,JSONPath=`.status.conditions[?(@.type=="Degraded")].status`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
 // HyperFleetConfig is the Schema for the hyperfleetconfigs API. It is a

config/crd/bases/hyperfleet.redhat.com_hyperfleetconfigs.yaml

@@ -26,6 +26,12 @@ spec:
     - jsonPath: .status.conditions[?(@.type=="Available")].status
       name: Available
       type: string
+    - jsonPath: .status.conditions[?(@.type=="Progressing")].status
+      name: Progressing
+      type: string
+    - jsonPath: .status.conditions[?(@.type=="Degraded")].status
+      name: Degraded
+      type: string
     - jsonPath: .metadata.creationTimestamp
       name: Age
       type: date
@@ -210,8 +216,9 @@ spec:
           status:
             description: |-
               HyperFleetConfigStatus defines the observed state of HyperFleetConfig. It is
-              populated by the bundle controller in later stories; this story defines the
-              schema only.
+              populated by the bundle controller after every reconcile (HYPERFLEET-1409),
+              rolling up each component's health into the Available/Progressing/Degraded
+              conditions.
             properties:
               conditions:
                 description: |-

docs/status-conditions.md

@@ -0,0 +1,72 @@
+# Status conditions
+
+`HyperFleetConfig` reports its installation health via `status.conditions`. This
+is deliberately a *different* vocabulary from the HyperFleet API's own
+condition dialect — the two are separate layers, and both are documented here
+so it's clear which one you're looking at.
+
+## Two layers
+
+- **Operator layer** (this document): `status.conditions` on the
+  `HyperFleetConfig` CR itself. It describes whether the operator has
+  successfully installed and is maintaining a healthy deployment of the
+  operand(s) selected by `spec.bundle` — i.e. "is the operator doing its job."
+  This follows the OpenShift `ClusterOperator` convention (`Available`,
+  `Progressing`, `Degraded`), minus `Upgradeable` (see architecture ADR-0019).
+- **API layer**: conditions reported by the HyperFleet API's own resources
+  (`Available`, `Ready`, `Reconciled`, `LastKnownReconciled`, per-adapter
+  `Successful`, etc. — see architecture ADR-0007 and ADR-0008). These describe
+  whether the API is successfully reconciling partner-managed resources
+  (clusters, node pools, etc.) — i.e. "is the API doing its job." They are
+  unrelated to and unaffected by the operator-layer conditions here.
+
+A `HyperFleetConfig` can be `Available=True` (the API Deployment is healthy)
+while individual API-layer resources are failing to reconcile, and vice versa:
+the operator conditions say nothing about the health of resources managed
+through the API.
+
+## Operator-layer condition types
+
+| Type | Meaning |
+|---|---|
+| `Available` | The operand (the API) is deployed and healthy. |
+| `Progressing` | The operator is actively rolling out a change to the operand. |
+| `Degraded` | The operator cannot reach or maintain the desired state. |
+
+Each condition's `observedGeneration` (and the top-level
+`status.observedGeneration`) reflects the `.metadata.generation` the operator
+had processed when the condition was last evaluated. `lastTransitionTime`
+changes only when a condition's `status` actually flips — reconciles that
+leave health unchanged do not touch it.
+
+If a reconcile fails before any component's health could actually be checked
+(e.g. a failed OIDC discovery, or a failed apply on the first operand),
+`Available` and `Progressing` are left exactly as they were last recorded
+rather than being guessed — only `Degraded` and `observedGeneration` are
+updated. This avoids publishing a fabricated "healthy" value alongside
+`Degraded=True` when the real state was never actually observed.
+
+## Reason strings
+
+Every condition write uses one of the following reasons — no ad hoc strings.
+Partners may read `status.conditions[].reason` as part of the published
+contract, so this table is the source of truth; the Go constants live
+alongside the condition types in `api/v1alpha1/hyperfleetconfig_types.go`.
+
+| Condition | Status | Reason | Meaning |
+|---|---|---|---|
+| Available | True | `DeploymentAvailable` | The operand Deployment reports Available; all desired replicas are ready. |
+| Available | False | `DeploymentUnavailable` | The operand Deployment is missing, or has zero available replicas. |
+| Available | False | `DeploymentNotReady` | The operand Deployment exists with some, but not all, replicas ready. |
+| Progressing | True | `RolloutInProgress` | The operand Deployment has not finished rolling out its current generation. |
+| Progressing | False | `RolloutComplete` | The operand Deployment is fully rolled out and stable. |
+| Degraded | False | `AsExpected` | No failure detected (the ClusterOperator convention's default). |
+| Degraded | True | `ReferencedSecretMissing` | A Secret referenced by `spec.api` (database, TLS, or JWKS) does not exist in the operator's namespace. |
+| Degraded | True | `ReconcileError` | Any other error during the most recent reconcile — JWKS discovery, reading referenced Secrets, resolving bundle components, or a component's render/apply. |
+
+## Notes on `Available`
+
+The operand's readiness probe (`/readyz`) only succeeds once the API has
+established a working database connection, so `Available=True` also implies
+the API can reach its configured PostgreSQL database — not just that the pod
+is running (`/healthz`, the liveness probe, does not check this).

internal/bundle/bundle.go

@@ -37,12 +37,15 @@ import (
 //
 //   - Render is a pure function (CR → desired objects); it must not read or write
 //     the cluster. The controller applies what it returns.
-//   - Conditions reports component health. It is consumed starting in
-//     HYPERFLEET-1409; until then the controller does not roll it into status.
+//   - Conditions is also cluster-access-free: it derives health from applied, the
+//     objects Render produced, already updated in place by apply.Objects with the
+//     server's current status (see internal/apply). This avoids giving every
+//     component its own client.Client and an extra round of API reads for state
+//     the controller already has. Consumed starting in HYPERFLEET-1409.
 type Component interface {
 	Name() string
 	Render(ctx context.Context, cr *hyperfleetv1alpha1.HyperFleetConfig) ([]client.Object, error)
-	Conditions(ctx context.Context, cr *hyperfleetv1alpha1.HyperFleetConfig) ([]metav1.Condition, error)
+	Conditions(ctx context.Context, cr *hyperfleetv1alpha1.HyperFleetConfig, applied []client.Object) ([]metav1.Condition, error)
 }
 
 // Config carries the inputs the resolver needs to construct components.

internal/component/api/api.go

@@ -20,6 +20,7 @@ import (
 	"context"
 	"fmt"
 
+	appsv1 "k8s.io/api/apps/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
@@ -161,11 +162,117 @@ func (c *Component) resolveJWKSource(cr *hyperfleetv1alpha1.HyperFleetConfig) (u
 	return c.ResolvedJWKSURL, ""
 }
 
-// Conditions reports the component's health as metav1.Conditions. The contract is
-// defined now (HYPERFLEET-1407) so it need not be reopened next story, but its
-// output is not yet rolled up into status.conditions — real health derivation and
-// status wiring land in HYPERFLEET-1409. Returning nil until then keeps the
-// reconciler from writing status prematurely.
-func (c *Component) Conditions(_ context.Context, _ *hyperfleetv1alpha1.HyperFleetConfig) ([]metav1.Condition, error) {
-	return nil, nil
+// Conditions reports the component's health as metav1.Conditions, derived from
+// the live state of the Deployment Render produced (already updated in place by
+// apply.Objects with the server's current status — see bundle.Component). It
+// never reads the cluster itself.
+//
+// Available reflects whether the Deployment is up: True only once all desired
+// replicas are ready, distinguishing "not present at all" (DeploymentUnavailable)
+// from "up but partially ready" (DeploymentNotReady). Progressing is derived from
+// replica-count/generation lag rather than trusting the Deployment's own
+// "Progressing" condition Reason verbatim, since that built-in condition stays
+// True/NewReplicaSetAvailable even at steady state, which is not what
+// HyperFleetConfig's Progressing means.
+func (c *Component) Conditions(_ context.Context, _ *hyperfleetv1alpha1.HyperFleetConfig, applied []client.Object) ([]metav1.Condition, error) {
+	dep := findDeployment(applied)
+	return []metav1.Condition{
+		availableCondition(dep),
+		progressingCondition(dep),
+	}, nil
+}
+
+// findDeployment returns the API Deployment from applied, or nil if absent.
+func findDeployment(applied []client.Object) *appsv1.Deployment {
+	for _, o := range applied {
+		if dep, ok := o.(*appsv1.Deployment); ok && dep.Name == ResourceName {
+			return dep
+		}
+	}
+	return nil
+}
+
+// desiredReplicas returns dep.Spec.Replicas, defaulting to 1 to match
+// render.go's current fixed baseline (Replicas is not yet configurable).
+func desiredReplicas(dep *appsv1.Deployment) int32 {
+	if dep.Spec.Replicas != nil {
+		return *dep.Spec.Replicas
+	}
+	return 1
+}
+
+// availableCondition derives Available from the Deployment's replica counts.
+func availableCondition(dep *appsv1.Deployment) metav1.Condition {
+	if dep == nil {
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionAvailable,
+			Status:  metav1.ConditionFalse,
+			Reason:  hyperfleetv1alpha1.ReasonDeploymentUnavailable,
+			Message: "the API Deployment does not exist",
+		}
+	}
+
+	desired := desiredReplicas(dep)
+
+	switch {
+	case desired == 0:
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionAvailable,
+			Status:  metav1.ConditionTrue,
+			Reason:  hyperfleetv1alpha1.ReasonDeploymentAvailable,
+			Message: "the API Deployment is scaled to zero",
+		}
+	case dep.Status.AvailableReplicas == 0:
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionAvailable,
+			Status:  metav1.ConditionFalse,
+			Reason:  hyperfleetv1alpha1.ReasonDeploymentUnavailable,
+			Message: "the API Deployment has no available replicas",
+		}
+	case dep.Status.AvailableReplicas < desired:
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionAvailable,
+			Status:  metav1.ConditionFalse,
+			Reason:  hyperfleetv1alpha1.ReasonDeploymentNotReady,
+			Message: fmt.Sprintf("the API Deployment has %d/%d replicas available", dep.Status.AvailableReplicas, desired),
+		}
+	default:
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionAvailable,
+			Status:  metav1.ConditionTrue,
+			Reason:  hyperfleetv1alpha1.ReasonDeploymentAvailable,
+			Message: "the API Deployment is available",
+		}
+	}
+}
+
+// progressingCondition derives Progressing from replica-count and generation
+// lag: the Deployment has not caught up with its most recently observed
+// generation, or not all replicas have been updated to the current template.
+func progressingCondition(dep *appsv1.Deployment) metav1.Condition {
+	if dep == nil {
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionProgressing,
+			Status:  metav1.ConditionTrue,
+			Reason:  hyperfleetv1alpha1.ReasonRolloutInProgress,
+			Message: "the API Deployment does not exist yet",
+		}
+	}
+
+	desired := desiredReplicas(dep)
+
+	if dep.Status.ObservedGeneration < dep.Generation || dep.Status.UpdatedReplicas < desired {
+		return metav1.Condition{
+			Type:    hyperfleetv1alpha1.ConditionProgressing,
+			Status:  metav1.ConditionTrue,
+			Reason:  hyperfleetv1alpha1.ReasonRolloutInProgress,
+			Message: "the API Deployment rollout has not completed",
+		}
+	}
+	return metav1.Condition{
+		Type:    hyperfleetv1alpha1.ConditionProgressing,
+		Status:  metav1.ConditionFalse,
+		Reason:  hyperfleetv1alpha1.ReasonRolloutComplete,
+		Message: "the API Deployment rollout is complete",
+	}
 }