Extend with syncedFalse approach

* Try approach with invalidation synced status on XR
* General example cleanup

Signed-off-by: Yury Tsarev <yury@upbound.io>

Author: ytsarev

NOTES.txt

@@ -7,7 +7,7 @@ A Crossplane Composition Function for implementing manual approval workflows.
 The `function-approve` provides a serverless approval mechanism at the Crossplane level that:
 
 1. Tracks changes to a specified field by computing a hash
-2. Pauses reconciliation when changes are detected
+2. Pauses reconciliation when changes are detected (using either pause annotation or Synced=False condition)
 3. Requires explicit approval before allowing reconciliation to continue
 4. Prevents drift by storing previously approved state
 
@@ -73,6 +73,7 @@ spec:
 | `pauseAnnotation` | string | Annotation to use for pausing reconciliation. Default: `crossplane.io/paused` |
 | `detailedCondition` | bool | Whether to add detailed information to conditions. Default: `true` |
 | `approvalMessage` | string | Message to display when approval is required. Default: `Changes detected. Approval required.` |
+| `setSyncedFalse` | bool | Use Synced=False condition instead of pause annotation. Default: `false` |
 
 ## Using with Custom Resources
 
@@ -142,6 +143,32 @@ kubectl patch xapproval example --type=merge --subresource=status -p '{"status":
 - Use RBAC to control who can approve changes by restricting access to the status subresource
 - Consider implementing additional verification steps or multi-party approval in your workflow
 
+## Pausing Reconciliation Methods
+
+The function supports two methods to pause reconciliation when changes are detected:
+
+### 1. Pause Annotation (Default)
+
+By default, the function adds the `crossplane.io/paused` annotation (or specified annotation) to pause reconciliation:
+
+```yaml
+pauseAnnotation: "crossplane.io/paused"
+setSyncedFalse: false  # Or omit this field as it defaults to false
+```
+
+### 2. Synced=False Condition
+
+Alternatively, the function can set the Synced condition to False instead of using an annotation:
+
+```yaml
+setSyncedFalse: true
+```
+
+This approach may be preferred in environments where:
+- Annotations are subject to stricter validation or policies
+- You want to leverage Crossplane's native condition-based reconciliation control
+- You need better integration with monitoring systems that use conditions
+
 ## Complete Example
 
 Here's a complete example of a composition using `function-approve`:
@@ -169,6 +196,7 @@ spec:
       oldHashField: "status.approvedHash"
       detailedCondition: true
       approvalMessage: "Cluster changes require admin approval"
+      setSyncedFalse: true  # Use Synced=False condition instead of pause annotation
   - step: create-resources
     functionRef:
       name: function-patch-and-transform

README.md

@@ -1,123 +1,81 @@
-# Microsoft Graph API Function Examples
+# Approval Function Examples
 
-This directory contains practical examples that demonstrate the function-msgraph capabilities for querying Microsoft Graph API.
+This directory contains examples demonstrating the function-approve capabilities for implementing approval workflows in Crossplane.
 
 ## Prerequisites
 
 To run these examples, you need:
 
 1. The Crossplane CLI installed
-2. Valid Azure credentials with Microsoft Graph API permissions:
-   - User.Read.All (for user validation)
-   - Group.Read.All (for group operations)
-   - Application.Read.All (for service principal details)
+2. function-approve built and available
 
-## Update Credentials
+## Understanding the Approval Function
 
-Before running any examples, update `secrets/azure-creds.yaml` with your valid Azure credentials:
+The approval function provides a controlled way to manage changes to Crossplane resources, requiring manual approval before changes are applied. This is useful for scenarios where you want to review changes before they are applied to your infrastructure.
 
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: azure-account-creds
-type: Opaque
-stringData:
-  credentials: |
-    {
-      "clientId": "your-client-id",
-      "clientSecret": "your-client-secret",
-      "tenantId": "your-tenant-id",
-      "subscriptionId": "your-subscription-id"
-    }
-```
-
-## Core Examples
-
-### 1. User Validation
-
-Validate if specified Azure AD users exist:
-
-```shell
-crossplane render xr.yaml user-validation-example.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
-
-Dynamic `usersRef` variations:
-
-```shell
-crossplane render xr.yaml user-validation-example-status-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
-
-```shell
-crossplane render xr.yaml user-validation-example-context-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc --extra-resources=envconfig.yaml
-```
-
-```shell
-crossplane render xr.yaml user-validation-example-spec-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
-
-### 2. Group Membership
-
-Get all members of a specified Azure AD group:
-
-```shell
-crossplane render xr.yaml group-membership-example.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
+The function works by:
+1. Computing a hash of specified data in your composite resource
+2. Checking if the hash has changed since the last approved version
+3. Pausing reconciliation if changes are detected and approval is needed
+4. Resuming reconciliation once changes are approved
 
-Dynamic `groupRef` variations:
+## Running the Examples
 
-```shell
-crossplane render xr.yaml group-membership-example-status-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
+### Basic Example with Pause Annotation
 
-```shell
-crossplane render xr.yaml group-membership-example-context-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc --extra-resources=envconfig.yaml
-```
+The default behavior uses the `crossplane.io/paused` annotation to pause reconciliation:
 
 ```shell
-crossplane render xr.yaml group-membership-example-spec-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
+crossplane render xr.yaml composition.yaml functions.yaml
 ```
 
-### 3. Group Object IDs
+### Example with Synced=False Condition
 
-Get object IDs for specified Azure AD groups:
+This alternative approach uses the Synced=False condition instead of the pause annotation:
 
 ```shell
-crossplane render xr.yaml group-objectids-example.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
+crossplane render xr.yaml composition.yaml functions.yaml
 ```
 
-Dynamic `groupsRef` variations:
-
-```shell
-crossplane render xr.yaml group-objectids-example-status-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
-
-```shell
-crossplane render xr.yaml group-objectids-example-context-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc --extra-resources=envconfig.yaml
-```
+The `setSyncedFalse: true` option in the composition enables this behavior.
 
-```shell
-crossplane render xr.yaml group-objectids-example-spec-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
+## Configuration Options
 
-### 4. Service Principal Details
+The function supports these configuration options:
 
-Get details of specified service principals:
+- `dataField`: Specifies which field to monitor for changes (required)
+- `approvalField`: Status field to check for approval (default: "status.approved")
+- `oldHashField`: Where to store the approved hash (default: "status.oldHash")
+- `newHashField`: Where to store the current hash (default: "status.newHash")
+- `pauseAnnotation`: Annotation used to pause reconciliation (default: "crossplane.io/paused")
+- `detailedCondition`: Whether to include hash details in conditions (default: true)
+- `approvalMessage`: Custom message for approval required condition
+- `setSyncedFalse`: Use Synced=False condition instead of pause annotation (default: false)
 
-```shell
-crossplane render xr.yaml service-principal-example.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
+## Approval Workflow
 
-Dynamic `servicePrinicpalsRef` variations:
+1. Make changes to the resource's spec
+2. The function detects changes and pauses reconciliation
+3. Review the changes through the resource's conditions
+4. Set the approval field (default: `status.approved: true`)
+5. The function detects approval and resumes reconciliation
 
-```shell
-crossplane render xr.yaml service-principal-example-status-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
+## Example With setSyncedFalse
 
-```shell
-crossplane render xr.yaml service-principal-example-context-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc --extra-resources=envconfig.yaml
-```
+In some environments, it may be preferable to use Synced=False condition instead of annotations.
+The `setSyncedFalse: true` option enables this alternative approach:
 
-```shell
-crossplane render xr.yaml service-principal-example-spec-ref.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -rc
-```
+```yaml
+apiVersion: approve.fn.crossplane.io/v1alpha1
+kind: Input
+dataField: "spec.resources"
+approvalField: "status.approved"
+newHashField: "status.newHash"
+oldHashField: "status.oldHash"
+detailedCondition: true
+approvalMessage: "Changes detected. Administrative approval required."
+setSyncedFalse: true
+```
+
+When enabled, this sets the Synced condition to False instead of adding the pause annotation,
+providing the same pause functionality through a different mechanism.

example/README.md

@@ -6,6 +6,7 @@ spec:
   compositeTypeRef:
     apiVersion: example.crossplane.io/v1
     kind: XApproval
+  mode: Pipeline
   pipeline:
   - step: require-approval
     functionRef:
@@ -20,24 +21,21 @@ spec:
       pauseAnnotation: "crossplane.io/paused"
       detailedCondition: true
       approvalMessage: "Changes detected. Administrative approval required."
+      setSyncedFalse: true
   - step: render-resources
     functionRef:
       name: function-patch-and-transform
     input:
-      apiVersion: pt.fn.crossplane.io/v1alpha1
+      apiVersion: pt.fn.crossplane.io/v1beta1
       kind: Resources
       resources:
-      - name: example-configmap
+      - name: example-envconfig
         base:
-          apiVersion: v1
-          kind: ConfigMap
-          metadata:
-            name: example-configmap
-          data:
-            key1: value1
+          apiVersion: apiextensions.crossplane.io/v1beta1
+          kind: EnvironmentConfig
         patches:
         - type: FromCompositeFieldPath
           fromFieldPath: spec.resources.data
           toFieldPath: data
           policy:
-            fromFieldPath: Required
+            fromFieldPath: Required

example/claim.yaml

@@ -44,4 +44,4 @@ spec:
         required:
         - spec
         type: object
-    served: true
+    served: true

example/composition.yaml

@@ -13,4 +13,4 @@ kind: Function
 metadata:
   name: function-patch-and-transform
 spec:
-  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.2.1
+  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.9.0