Documentation: Add porch.kpt.dev/push-on-render-failure annotation behavior (kptdev#483)

* Added documentation for push-on-render-failure annotation

Signed-off-by: aravind.est <aravindhan.a@est.tech>

* Fix copilot review comments.

Signed-off-by: aravind.est <aravindhan.a@est.tech>

* Address review comments - 2

Signed-off-by: aravind.est <aravindhan.a@est.tech>

---------

Signed-off-by: aravind.est <aravindhan.a@est.tech>

Author: aravindtga

docs/content/en/docs/11_glossary/_index.md

@@ -229,9 +229,19 @@ An executable that takes Kubernetes resources as input and produces Kubernetes r
 
 ### Rendering
 
-The process of executing KRM functions defined in a package's Kptfile pipeline. Rendering occurs automatically when Draft packages are modified (via push operations). Function results are stored in the PackageRevision's `status.renderStatus` field.
+The process of executing KRM functions defined in a package's Kptfile pipeline. Rendering occurs automatically when Draft packages are modified (via push operations). Function results are stored in the PackageRevisionResources API resource's `status.renderStatus` field.
 
-*See also*: [KRM Function](#krm-function), [Function Runner](#function-runner)
+By default, render failures prevent resources from being persisted. The `porch.kpt.dev/push-on-render-failure` annotation can override this behavior to save work-in-progress packages even when rendering fails.
+
+*See also*: [KRM Function](#krm-function), [Function Runner](#function-runner), [Push on Render Failure](#push-on-render-failure)
+
+### Push on Render Failure
+
+An annotation (`porch.kpt.dev/push-on-render-failure: "true"`) that enables persisting Draft PackageRevision resources even when the kpt function render pipeline fails during resource updates. This allows saving work-in-progress packages during iterative development when the pipeline isn't fully functional yet. It does not apply to package creation operations (clone, init, edit, copy).
+
+The behavior of partially-rendered resources can be further controlled via Kptfile annotations (see [kpt documentation](https://kpt.dev/book/04-using-functions/#debugging-render-failures)).
+
+*See also*: [Rendering](#rendering), [Draft](#draft)
 
 ### Task
 

docs/content/en/docs/2_concepts/functions.md

@@ -79,7 +79,13 @@ The `renderStatus` field contains:
 - Per-function results including exit codes and validation messages
 - Error details if function execution failed
 
-Validation failures prevent Draft package revisions from being created and PackageRevisionResources from being updated.
+{{< alert title="Note" color="primary" >}}
+By default, render failures (including validation failures) prevent Draft package revisions from being created and PackageRevisionResources from
+being updated. However, when **updating resources on an existing Draft** (e.g. via `porchctl rpkg push`),
+adding the `porch.kpt.dev/push-on-render-failure: "true"` annotation **to the PackageRevision** allows persisting resources even when rendering fails,
+enabling iterative development on incomplete packages.
+{{< /alert >}}
+
 
 ## Key Points
 
@@ -88,4 +94,5 @@ Validation failures prevent Draft package revisions from being created and Packa
 - Functions automatically execute during package rendering on Draft package revisions
 - Function results are stored in `status.renderStatus` of the PackageRevisionResources view of a package revision
 - Published packages are immutable - functions don't re-execute after publication
-- Validation failures block Draft package creation and package revision resource updates
+- By default, render failures (including validation failures) block Draft package creation and package revision resource updates
+- When updating resources on an existing Draft (e.g., `porchctl rpkg push`), the `porch.kpt.dev/push-on-render-failure: "true"` annotation allows persisting resources despite render failures

docs/content/en/docs/4_tutorials_and_how-tos/working_with_package_revisions/_index.md

@@ -168,6 +168,11 @@ Common issues when working with PackageRevisions and their solutions:
 - Check function image availability and version
 - Verify function configuration in Kptfile
 - Review function logs in Porch server output during push operations
+- **To save work-in-progress despite failures**: Add `porch.kpt.dev/push-on-render-failure: "true"` annotation to the PackageRevision
+  ```bash
+  kubectl annotate packagerevision <name> porch.kpt.dev/push-on-render-failure=true
+  ```
+- The behavior of partially-rendered resources can be further controlled via Kptfile annotations (see [kpt documentation](https://kpt.dev/book/04-using-functions/#debugging-render-failures))
 
 ---
 

docs/content/en/docs/5_architecture_and_components/controllers/interactions.md

@@ -298,7 +298,10 @@ Fetch PackageRevisionResources
 - Porch automatically executes render after resource update
 - Runs function pipeline from Kptfile
 - Returns RenderStatus with function results
-- Errors don't prevent draft closure (status indicates failure)
+- **Render failure handling**:
+  - Default: Errors prevent draft closure (no resources persisted)
+  - With `porch.kpt.dev/push-on-render-failure: "true"`: Draft closed even on failure (resources persisted)
+  - Error always returned regardless of persistence
 
 ### Deletion Handling
 

docs/content/en/docs/5_architecture_and_components/engine/functionality/draft-commit-orchestration.md

@@ -359,9 +359,13 @@ UpdatePackageResources Request
         ↓
   Execute Render
         ↓
-  Error? ──Yes──> Return Error + RenderStatus
-        │
-        No
+  Error? ──Yes──> Check `porch.kpt.dev/push-on-render-failure` annotation
+        │                           ↓
+        No                    "true"? ──Yes──> Close Draft + Return Error
+        ↓                           │
+        │                           No
+        │                           ↓
+        │                      Return Error (no push)
         ↓
   Close Draft (no lifecycle change)
         ↓
@@ -376,7 +380,11 @@ UpdatePackageResources Request
 5. **Update to draft** (opens existing revision)
 6. **Apply resource mutations** through task handler
 7. **Execute render** (run function pipeline)
-8. **Close draft** without lifecycle change
+8. **Check render result**:
+   - Success: Close draft and return
+   - Failure: Check `porch.kpt.dev/push-on-render-failure` annotation
+     - If `"true"`: Close draft (persist resources) and return error
+     - Otherwise: Return error without persisting
 9. **Return** updated package revision and render status
 
 ### Resource Mutation
@@ -403,7 +411,40 @@ TaskHandler.DoPRResourceMutations
 - Runs configured KRM function pipeline
 - Functions can validate, transform, generate resources
 - Results returned in RenderStatus
-- Errors don't prevent draft closure (render status indicates failure)
+- **Render failure handling**:
+  - Default behavior: Render errors prevent draft closure (no resources persisted)
+  - With `porch.kpt.dev/push-on-render-failure: "true"` annotation: Draft is closed even on render failure
+  - The behavior of partially-rendered resources can be further controlled via Kptfile annotations (see [kpt documentation](https://kpt.dev/book/04-using-functions/#debugging-render-failures))
+  - Error is always returned to caller regardless of persistence behavior
+
+### Persisting Resources on Render Failure
+
+The `porch.kpt.dev/push-on-render-failure` annotation enables saving work-in-progress packages even when the kpt function render pipeline fails:
+
+**Annotation behavior:**
+
+| PackageRevision Annotation | Kptfile Annotation | Render Result | Behavior |
+|----------------------------|-------------------|---------------|----------|
+| Not set | Not set | Success | Push rendered resources |
+| Not set | Not set | Failure | No push, error returned |
+| `"true"` | Not set | Success | Push rendered resources |
+| `"true"` | Not set | Failure | Push unrendered resources, error returned |
+| `"true"` | `"true"` | Failure | Push partially-rendered resources, error returned |
+| `"false"` | Not set | Failure | No push, error returned |
+| Not set | `"true"` | Failure | No push, error returned (kpt may have produced partial output internally) |
+
+**How to use:**
+```bash
+# Add annotation to PackageRevision
+kubectl annotate packagerevision <name> porch.kpt.dev/push-on-render-failure=true
+```
+
+**Important notes:**
+- Only applies to Draft PackageRevisions during resource updates (via `UpdatePackageResources`)
+- Does not apply to package creation operations (init, clone, edit, copy)
+- Error is always returned even when resources are persisted
+- The behavior of partially-rendered resources can be further controlled via Kptfile annotations (see [kpt documentation](https://kpt.dev/book/04-using-functions/#debugging-render-failures))
+- In rare cases (e.g., internal errors during resource persistence), push may be prevented regardless of the annotation
 
 ## Rollback Mechanism
 

docs/content/en/docs/6_configuration_and_deployments/configurations/opentelemetry.md

@@ -11,7 +11,7 @@ Porch supports OpenTelemetry observability through the [autoexport package](http
 
 All Porch components (porch-server, porch-controllers, function-runner, and wrapper-server) support OpenTelemetry configuration through standardized environment variables as defined by the [OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/).
 
-{{% alert title="Note" color="info" %}}
+{{% alert title="Note" color="primary" %}}
 **Current Implementation Status**: Porch currently implements metrics and traces export. Logs export is not supported.
 {{% /alert %}}
 

docs/content/en/docs/6_configuration_and_deployments/configurations/repository-sync.md

@@ -5,7 +5,7 @@ weight: 1
 description: "Configure repository synchronization for Porch Repositories"
 ---
 
-{{% alert title="Documentation Location" color="info" %}}
+{{% alert title="Documentation Location" color="primary" %}}
 This documentation is currently located in the system configuration section but should be moved to a more logical location as it's about configuring individual Repository resources, not system-wide settings. This may be relocated in future documentation updates.
 {{% /alert %}}
 

docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md

@@ -30,7 +30,7 @@ These features can be configured **after** deployment:
 
 - [Git Authentication]({{% relref "../configurations/components/porch-server-config/git-authentication" %}}) - Configure Porch Server authentication for private Git repositories
 
-{{% alert title="Note" color="info" %}}
+{{% alert title="Note" color="primary" %}}
 [Repository Sync]({{% relref "../configurations/repository-sync" %}}) configuration is currently located in the system configuration section but should be moved to a more logical location as it's about configuring individual Repository resources, not system-wide settings.
 {{% /alert %}}