docs: enhance MetricsAvailable condition documentation

- Add MetricsAvailable condition fix to CHANGELOG v0.5.0
- Enhance CRD reference with detailed condition documentation
- Add Operations & Monitoring section to main README
- Include examples of condition usage and kubectl commands
- Link to comprehensive metrics health monitoring guide

This update ensures the MetricsAvailable condition feature (PR #567)
is properly documented across all relevant guides.

Author: github-actions[bot]

README.md

@@ -64,6 +64,10 @@ See the [Installation Guide](docs/user-guide/installation.md) for detailed instr
 - [CRD Reference](docs/user-guide/crd-reference.md)
 - [Multi-Controller Isolation](docs/user-guide/multi-controller-isolation.md)
 
+### Operations & Monitoring
+- [Metrics Health Monitoring](docs/metrics-health-monitoring.md) - Status conditions and troubleshooting
+- [Prometheus Metrics](docs/integrations/prometheus.md)
+
 <!-- 
 
 ### Tutorials
@@ -74,7 +78,6 @@ See the [Installation Guide](docs/user-guide/installation.md) for detailed instr
 ### Integrations
 - [HPA Integration](docs/integrations/hpa-integration.md)
 - [KEDA Integration](docs/integrations/keda-integration.md)
-- [Prometheus Metrics](docs/integrations/prometheus.md)
 
 <!-- 
 

docs/CHANGELOG-v0.5.0.md

@@ -135,6 +135,40 @@ query := fmt.Sprintf(`vllm_kv_cache_usage{namespace="%s"}`, escapedNamespace)
 **Documentation:**
 - [Prometheus Integration - PromQL Injection Prevention](integrations/prometheus.md#promql-injection-prevention)
 
+## Bug Fixes
+
+### MetricsAvailable Condition Always Set in Status (PR #567)
+
+**Problem:**
+The `MetricsAvailable` condition was not consistently appearing in VariantAutoscaling status, making it difficult for operators to diagnose metrics collection issues.
+
+**Root Cause:**
+The condition was being set on a local VA object that was never persisted to the API server. The condition needed to flow through the DecisionCache to reach the controller.
+
+**Solution:**
+- Added `MetricsAvailable`, `MetricsReason`, and `MetricsMessage` fields to `VariantDecision` struct
+- Engine populates these fields in the decision cache based on whether metrics data is available
+- Controller reads from cache and sets the condition on VA status
+- Condition is now set even when pods aren't ready yet (MetricsAvailable=False with helpful message)
+
+**Behavior:**
+- **MetricsAvailable=True**: Metrics data is available (allocation from metrics collection OR decision from saturation analysis)
+- **MetricsAvailable=False**: No metrics available - pods may not be ready or metrics not yet scraped
+
+**Constants Extracted:**
+- `MetricsReasonAvailable` / `MetricsReasonUnavailable`
+- `MetricsMessageAvailable` / `MetricsMessageUnavailable`
+
+**Benefits:**
+- ✅ Operators can always see metrics availability status
+- ✅ Clear diagnostic messages for troubleshooting
+- ✅ Consistent condition reporting across all scenarios
+- ✅ Better visibility into controller state
+
+**Documentation:**
+- [Metrics Health Monitoring](metrics-health-monitoring.md)
+- [CRD Reference - Conditions](user-guide/crd-reference.md)
+
 ## Minor Improvements
 
 ### Helper Functions
@@ -205,7 +239,9 @@ E2E tests updated:
 ## References
 
 - PR #549: https://github.com/llm-d-incubation/workload-variant-autoscaler/pull/549
+- PR #567: https://github.com/llm-d-incubation/workload-variant-autoscaler/pull/567
 - Commit: 14e2bd88 - fix: pending-aware scaling and E2E test stability improvements
+- Commit: 2963cc73 - fix: always set MetricsAvailable condition in VA status
 
 ---
 

docs/user-guide/crd-reference.md

@@ -128,3 +128,70 @@ _Appears in:_
 | `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#condition-v1-meta) array_ | Conditions represent the latest available observations of the VariantAutoscaling's state |  | Optional: \{\} <br /> |
 
 
+## Status Conditions
+
+WVA uses standard Kubernetes conditions to report the health and state of each VariantAutoscaling resource.
+
+### Condition Types
+
+#### MetricsAvailable
+
+Indicates whether vLLM metrics are available from Prometheus for this variant.
+
+**Status Values:**
+- `True`: Metrics data is available
+- `False`: No metrics available (pods not ready or metrics not scraped)
+
+**Common Reasons:**
+- `MetricsAvailable`: Saturation metrics data is available for scaling decisions
+- `MetricsUnavailable`: No saturation metrics available
+
+**Example:**
+```yaml
+conditions:
+- type: MetricsAvailable
+  status: "True"
+  reason: MetricsAvailable
+  message: "Saturation metrics data is available for scaling decisions"
+  lastTransitionTime: "2026-01-09T22:00:00Z"
+```
+
+#### OptimizationReady
+
+Indicates whether the optimization engine ran successfully.
+
+**Status Values:**
+- `True`: Optimization completed
+- `False`: Optimization failed or cannot run
+
+**Common Reasons:**
+- `OptimizationSucceeded`: Optimization completed successfully
+- `SaturationOnlyMode`: Operating in saturation-only mode
+- `SaturationSafetyOverride`: Saturation safety override applied
+
+**Example:**
+```yaml
+conditions:
+- type: OptimizationReady
+  status: "True"
+  reason: OptimizationSucceeded
+  message: "Hybrid mode: scale-up decision (target: 3 replicas)"
+  lastTransitionTime: "2026-01-09T22:00:00Z"
+```
+
+### Viewing Conditions
+
+```bash
+# Quick view with MetricsReady column
+kubectl get variantautoscaling -A
+
+# Detailed condition information
+kubectl describe variantautoscaling <name> -n <namespace>
+
+# Extract conditions as JSON
+kubectl get variantautoscaling <name> -n <namespace> -o jsonpath='{.status.conditions}' | jq
+```
+
+For comprehensive information on metrics health monitoring and troubleshooting, see [Metrics Health Monitoring](../metrics-health-monitoring.md).
+
+