Merge pull request #776 from a-hilaly/new-docs

docs: enhance RGD, SimpleSchema, and Instance documentation

Author: k8s-ci-robot

website/docs/docs/concepts/00-resource-group-definitions.md

@@ -137,7 +137,10 @@ correctness and set up the necessary components:
    - Checks that referenced values exist and are of the correct type
    - Confirms resource dependencies form a valid Directed Acyclic Graph(DAG)
      without cycles
-   - Validates all CEL expressions in status fields and conditions
+   - Validates all CEL expressions in status fields and conditions using CEL's native type system
+     - Validates field references exist in the actual resource schemas
+     - Ensures expressions return types compatible with their target fields
+     - Checks type compatibility statically without executing expressions
 
 2. **API Generation**: kro generates and registers a new CRD in your cluster
    based on your schema. For example, if your **ResourceGraphDefinition** defines a
@@ -149,12 +152,14 @@ correctness and set up the necessary components:
    - Integrates seamlessly with kubectl and other Kubernetes tools
 
 3. **Controller Configuration**: kro configures itself to watch for instances of
-   your new API and:
+   your new API and their managed resources:
 
    - Creates all required resources following the dependency order
    - Manages references and value passing between resources
    - Handles the complete lifecycle for create, update, and delete operations
    - Keeps status information up to date based on actual resource states
+   - Automatically detects and reconciles drift in managed resources
+   - Triggers reconciliation when any managed resource changes
 
 For instance, when you create a `WebApplication` ResourceGraphDefinition, kro generates
 the `webapplications.kro.run` CRD. When users create instances of this API, kro

website/docs/docs/concepts/10-simple-schema.md

@@ -268,22 +268,70 @@ username: string | minLength=3 maxLength=20 pattern="^[a-zA-Z0-9_]+$"
 tags: "[]string" | uniqueItems=true minItems=1 maxItems=10 description="1-10 unique tags"
 ```
 
+:::warning Floating Point Precision
+When using `float` or `double` types in CEL expressions (particularly in `readyWhen` or `includeWhen` conditions), be aware of floating point precision issues that could cause unexpected behavior. Avoid comparing floating point values for equality in conditional logic. Prefer using `string`, `integer`, or `boolean` types whenever possible to avoid precision-related oscillations in resource state.
+:::
+
 ## Status Fields
 
 Status fields use CEL expressions to reference values from resources. kro
 automatically:
 
 - Infers the correct types from the expressions
-- Validates that referenced resources exist
+- Validates that referenced resources exist at ResourceGraphDefinition creation time
 - Updates values when the underlying resources change
+- Validates type compatibility using CEL's native type system
 
 ```yaml
 status:
   # Types are inferred from the referenced fields
-  availableReplicas: ${deployment.status.availableReplicas}
-  endpoint: ${service.status.loadBalancer.ingress[0].hostname}
+  availableReplicas: ${deployment.status.availableReplicas}  # integer
+  endpoint: ${service.status.loadBalancer.ingress[0].hostname}  # string
+  metadata: ${deployment.metadata}  # object
+```
+
+### Single vs Multi-Expression Fields
+
+Status fields can contain either a single CEL expression or multiple expressions concatenated together:
+
+**Single Expression Fields** can be any type:
+```yaml
+status:
+  replicas: ${deployment.status.replicas}  # integer
+  metadata: ${deployment.metadata}  # object
+  name: ${deployment.metadata.name}  # string
+  ready: ${deployment.status.conditions.exists(c, c.type == 'Available')}  # boolean
 ```
 
+**Multi-Expression Fields** (string templating) must contain only string expressions:
+```yaml
+status:
+  # ✓ Valid - all expressions return strings
+  endpoint: "https://${service.metadata.name}.${service.metadata.namespace}.svc.cluster.local"
+
+  # ✓ Valid - explicit string conversion
+  summary: "Replicas: ${string(deployment.status.replicas)}, Ready: ${string(deployment.status.ready)}"
+
+  # ✗ Invalid - concatenating non-string types
+  invalid: "${deployment.status.replicas}-${deployment.metadata}"  # Will fail validation
+```
+
+Multi-expression fields are useful for string templating scenarios like constructing URLs, connection strings, or IAM policies:
+
+```yaml
+status:
+  iamPolicy: |
+    {
+      "Effect": "Allow",
+      "Resource": "arn:aws:s3:::${bucket.metadata.name}/*",
+      "Principal": "${serviceAccount.metadata.name}"
+    }
+```
+
+:::tip
+Use explicit `string()` conversions when concatenating non-string values to ensure type compatibility.
+:::
+
 ## Default Status Fields
 
 kro automatically injects two fields to every instance's status:
@@ -295,27 +343,30 @@ An array of condition objects tracking the instance's state:
 ```yaml
 status:
   conditions:
-    - type: string # e.g., "Ready", "Progressing"
+    - type: string # e.g., "Ready", "InstanceManaged", "GraphResolved", "ResourcesReady"
       status: string # "True", "False", "Unknown"
       lastTransitionTime: string
+      observedGeneration: integer
       reason: string
       message: string
 ```
 
-Common condition types:
+kro provides a hierarchical condition structure:
+
+- `Ready`: Top-level condition indicating the instance is fully operational
+  - `InstanceManaged`: Instance finalizers and labels are properly set
+  - `GraphResolved`: Runtime graph has been created and resources resolved
+  - `ResourcesReady`: All resources in the graph are created and ready
 
-- `Ready`: Instance is fully reconciled
-- `Progressing`: Working towards desired state
-- `Degraded`: Operational but not optimal
-- `Error`: Reconciliation error occurred
+The `Ready` condition aggregates the state of all sub-conditions and only becomes `True` when all sub-conditions are `True`. Each condition includes an `observedGeneration` field that tracks which generation of the instance the condition reflects.
 
 ### 2. State
 
 A high-level summary of the instance's status:
 
 ```yaml
 status:
-  state: string # Ready, Progressing, Degraded, Unknown, Deleting
+  state: string # ACTIVE, IN_PROGRESS, FAILED, DELETING, ERROR
 ```
 
 :::tip

website/docs/docs/concepts/15-instances.md

@@ -52,6 +52,24 @@ state, providing features like:
 - Consistent state management
 - Status tracking
 
+### Reactive Reconciliation
+
+kro automatically watches all resources managed by an instance and triggers
+reconciliation when any of them change. This means:
+
+- **Child Resource Changes**: When a managed resource (like a Deployment or Service) is
+  modified, kro detects the change and reconciles the instance to ensure it matches
+  the desired state defined in your ResourceGraphDefinition.
+
+- **Drift Detection**: If a resource is manually modified or deleted, kro will detect
+  the drift and automatically restore it to the desired state.
+
+- **Dependency Updates**: Changes to resources propagate through the dependency graph,
+  ensuring all dependent resources are updated accordingly.
+
+This reactive behavior ensures your instances maintain consistency without requiring
+manual intervention or periodic full reconciliations.
+
 ## Monitoring Your Instances
 
 KRO provides rich status information for every instance:
@@ -69,11 +87,30 @@ status:
   state: ACTIVE # High-level instance state
   availableReplicas: 3 # Status from Deployment
   conditions: # Detailed status conditions
-    - type: Ready
+    - lastTransitionTime: "2025-08-08T00:03:46Z"
+      message: instance is properly managed with finalizers and labels
+      observedGeneration: 1
+      reason: Managed
       status: "True"
-      lastTransitionTime: "2024-07-23T01:01:59Z"
-      reason: ResourcesAvailable
-      message: "All resources are available and configured correctly"
+      type: InstanceManaged
+    - lastTransitionTime: "2025-08-08T00:03:46Z"
+      message: runtime graph created and all resources resolved
+      observedGeneration: 1
+      reason: Resolved
+      status: "True"
+      type: GraphResolved
+    - lastTransitionTime: "2025-08-08T00:03:46Z"
+      message: all resources are created and ready
+      observedGeneration: 1
+      reason: AllResourcesReady
+      status: "True"
+      type: ResourcesReady
+    - lastTransitionTime: "2025-08-08T00:03:46Z"
+      message: ""
+      observedGeneration: 1
+      reason: Ready
+      status: "True"
+      type: Ready
 ```
 
 ### Understanding Status
@@ -88,17 +125,64 @@ Every instance includes:
    - `DELETING`: Indicates that the instance is in the process of being deleted.
    - `ERROR`: Indicates that an error occurred during instance processing.
 
-2. **Conditions**: Detailed status information
+2. **Conditions**: Detailed status information structured hierarchically
+
+   kro provides a top-level `Ready` condition that reflects the overall instance health. This condition is supported by three sub-conditions that track different phases of the reconciliation process:
+
+   - `InstanceManaged`: Instance finalizers and labels are properly set
+     - Ensures the instance is under kro's management
+     - Tracks whether cleanup handlers (finalizers) are configured
+     - Confirms instance is labeled with ownership and version information
+
+   - `GraphResolved`: Runtime graph has been created and resources resolved
+     - Validates that the resource graph has been successfully parsed
+     - Confirms all resource templates have been resolved
+     - Ensures dependencies between resources are properly understood
 
-   - `Ready`: Instance is fully operational
-   - `Progressing`: Changes are being applied
-   - `Degraded`: Operating but not optimal
-   - `Error`: Problems detected
+   - `ResourcesReady`: All resources in the graph are created and ready
+     - Tracks the creation and readiness of all managed resources
+     - Monitors the health of resources in topological order
+     - Reports when all resources have reached their ready state
+
+   - `Ready`: Instance is fully operational (top-level condition)
+     - Aggregates the state of all sub-conditions
+     - Only becomes True when all sub-conditions are True
+     - The primary condition to monitor for instance health
+
+   Each condition includes:
+   - `observedGeneration`: Tracks which generation of the instance this condition reflects
+   - `lastTransitionTime`: When the condition last changed state
+   - `reason`: A programmatic identifier for the condition state
+   - `message`: A human-readable description of the current state
 
 3. **Resource Status**: Status from your resources
    - Values you defined in your ResourceGraphDefinition's status section
    - Automatically updated as resources change
 
+## Debugging Instance Issues
+
+When an instance is not in the expected state, the condition hierarchy helps you quickly identify where the problem occurred:
+
+1. **Check the Ready condition first**
+   ```bash
+   kubectl get <your-kind> <instance-name> -o jsonpath='{.status.conditions[?(@.type=="Ready")]}'
+   ```
+
+2. **If Ready is False, check the sub-conditions** to identify which phase failed:
+
+   - If `InstanceManaged` is False: Check if there are issues with finalizers or instance labels
+   - If `GraphResolved` is False: The resource graph could not be created - check the ResourceGraphDefinition for syntax errors or invalid CEL expressions
+   - If `ResourcesReady` is False: One or more managed resources failed to become ready - check the error message for which resource failed
+
+3. **Use kubectl describe** to see all conditions and recent events:
+   ```bash
+   kubectl describe <your-kind> <instance-name>
+   ```
+
+4. **Check the observedGeneration** field in conditions:
+   - If `observedGeneration` is less than `metadata.generation`, the controller hasn't processed the latest changes yet
+   - If they match, the conditions reflect the current state of your instance
+
 ## Best Practices
 
 - **Version Control**: Keep your instance definitions in version control
@@ -111,7 +195,17 @@ Every instance includes:
 
 - **Active Monitoring**: Regularly check instance status beyond just "Running".
   Watch conditions, resource status, and events to catch potential issues early
-  and understand your application's health.
+  and understand your application's health. Focus on the `Ready` condition and
+  its sub-conditions to understand the reconciliation state.
+
+- **Monitor observedGeneration**: When making changes to an instance, verify that
+  `observedGeneration` in the conditions matches `metadata.generation` to ensure
+  kro has processed your changes.
+
+- **Leverage Reactive Reconciliation**: kro automatically detects and corrects drift
+  in managed resources. If you need to make manual changes to resources, update the
+  instance specification instead to ensure changes persist and align with your
+  desired state.
 
 - **Regular Reviews**: Periodically review your instance configurations to
   ensure they reflect current requirements and best practices. Update resource