Skip to content

Commit 54648b2

Browse files
jonasz-lasutytsarev
jonasz-lasut
and
ytsarev
authored
Issue#51/support operations (#54)
* Initial operations support * Test Operations, add capabilities * prepare failing tests with required operation fixes, removed connection details * Support for operations with annotation-based notification mechanism * Fix rsp.Desired, run manual tests and confirm the correct annotations are set * Fix linter * update readme * Update README.md Co-authored-by: Yury Tsarev <[email protected]> --------- Co-authored-by: Yury Tsarev <[email protected]>
1 parent 2885a63 commit 54648b2

File tree

11 files changed

+1026
-98
lines changed

11 files changed

+1026
-98
lines changed

‎README.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,125 @@ identity:
365365
type: AzureWorkloadIdentityCredentials
366366
```
367367

368+
## Operations support
369+
function-msgraph support every kind of [operations](https://docs.crossplane.io/latest/operations/operation/) but it only allows targeting Composite Resources
370+
Function omits the input.skipQueryWhenTargetHasData parameter when running in operation mode to enforce compability with Cron/Watch modes.
371+
CronOperations and WatchOperations are the most useful in context of graph queries, please check [examples](./example/operations/).
372+
### Operations and Compositions Working Together
373+
374+
**Important**: Operations and Compositions work in conjunction to provide a self-healing mechanism:
375+
376+
1. **Operations Role (Drift Detection)**:
377+
- Query Microsoft Graph API on schedule/watch events
378+
- Compare results with current XR status
379+
- Set drift detection annotations (but don't update status directly)
380+
381+
2. **Compositions Role (Drift Correction)**:
382+
- Run when XR is reconciled (triggered by annotation changes)
383+
- Check drift detection annotation
384+
- If drift detected, ignore `skipQueryWhenTargetHasData` flag and update status
385+
- Reset drift annotation to "false" after successful update
386+
387+
This creates a **two-phase self-healing system** where Operations monitor for changes and Compositions perform the actual data updates.
388+
### Operations results
389+
function-msgraph operations result in two annotations set on the XR:
390+
```yaml
391+
apiVersion: "example.org/v1"
392+
kind: XR
393+
metadata:
394+
name: "cool-xr"
395+
annotations:
396+
"function-msgraph/last-execution": "2025-01-01T00:00:00+01:00"
397+
"function-msgraph/last-execution-query-drift-detected": "false"
398+
```
399+
function-msgraph/last-execution sets RFC3339 timestamp informing about last succesful Operation run.
400+
function-msgraph/last-execution-query-drift-detected sets a boolean if there's a drift between input.target field's value and query result, which is used by function-msgraph in Composition context for self-healing. skipQueryWhenTargetHasData input parameter is ommited when drift detected annotation is set which leads to XR update and after that next Operation run sets the annotation back to "false".
401+
402+
### CronOperation
403+
CronOperation may be used to forcefully update XR's status in a predefined interval.
404+
That functionality may be especially useful for XRs that are business critical and should have the data refreshed without worrying about throttling.
405+
Supports only singular resource reference.
406+
407+
```yaml
408+
apiVersion: ops.crossplane.io/v1alpha1
409+
kind: CronOperation
410+
metadata:
411+
name: update-user-validation-for-critical-xr
412+
spec:
413+
schedule: "*/5 * * * *" # Every 5 minutes
414+
concurrencyPolicy: Forbid
415+
successfulHistoryLimit: 5
416+
failedHistoryLimit: 3
417+
operationTemplate:
418+
spec:
419+
mode: Pipeline
420+
pipeline:
421+
- step: user-validation
422+
functionRef:
423+
name: function-msgraph
424+
input:
425+
apiVersion: msgraph.fn.crossplane.io/v1alpha1
426+
kind: Input
427+
queryType: UserValidation
428+
# Replace these with actual users in your directory
429+
users:
430+
- "[email protected]"
431+
- "[email protected]"
432+
- "[email protected]"
433+
target: "status.validatedUsers"
434+
credentials:
435+
- name: azure-creds
436+
source: Secret
437+
secretRef:
438+
namespace: upbound-system
439+
name: azure-account-creds
440+
requirements:
441+
requiredResources:
442+
- requirementName: ops.crossplane.io/watched-resource
443+
apiVersion: example.crossplane.io/v1
444+
kind: XR
445+
name: business-critical-xr
446+
```
447+
### WatchOperation
448+
WatchOperation may be used to forcefully update XR's status based on match condition.
449+
For example it may be useful to refresh status in business critical XR's that are labeled with label `always-update: "true"`.
450+
```yaml
451+
apiVersion: ops.crossplane.io/v1alpha1
452+
kind: WatchOperation
453+
metadata:
454+
name: update-user-validation-for-critical-xrs
455+
spec:
456+
watch:
457+
apiVersion: example.crossplane.io/v1
458+
kind: XR
459+
matchLabels:
460+
always-update: "true"
461+
concurrencyPolicy: Allow
462+
operationTemplate:
463+
spec:
464+
mode: Pipeline
465+
pipeline:
466+
- step: user-validation
467+
functionRef:
468+
name: function-msgraph
469+
input:
470+
apiVersion: msgraph.fn.crossplane.io/v1alpha1
471+
kind: Input
472+
queryType: UserValidation
473+
# Replace these with actual users in your directory
474+
users:
475+
- "[email protected]"
476+
- "[email protected]"
477+
- "[email protected]"
478+
target: "status.validatedUsers"
479+
credentials:
480+
- name: azure-creds
481+
source: Secret
482+
secretRef:
483+
namespace: upbound-system
484+
name: azure-account-creds
485+
```
486+
368487
## References
369488
370489
- [Microsoft Graph API Overview](https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0)

‎example/operations/cronoperation.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
apiVersion: ops.crossplane.io/v1alpha1
2+
kind: CronOperation
3+
metadata:
4+
name: update-user-validation-for-critical-xr
5+
spec:
6+
schedule: "*/1 * * * *" # Every minute
7+
concurrencyPolicy: Forbid
8+
successfulHistoryLimit: 5
9+
failedHistoryLimit: 3
10+
operationTemplate:
11+
spec:
12+
mode: Pipeline
13+
pipeline:
14+
- step: user-validation
15+
functionRef:
16+
name: function-msgraph
17+
input:
18+
apiVersion: msgraph.fn.crossplane.io/v1alpha1
19+
kind: Input
20+
queryType: UserValidation
21+
# Replace these with actual users in your directory
22+
users:
23+
- "[email protected]"
24+
- "[email protected]"
25+
- "[email protected]"
26+
target: "status.validatedUsers"
27+
credentials:
28+
- name: azure-creds
29+
source: Secret
30+
secretRef:
31+
namespace: upbound-system
32+
name: azure-account-creds
33+
requirements:
34+
requiredResources:
35+
- requirementName: ops.crossplane.io/watched-resource
36+
apiVersion: example.crossplane.io/v1
37+
kind: XR
38+
name: business-critical-xr

‎example/operations/operation.yaml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
apiVersion: ops.crossplane.io/v1alpha1
2+
kind: Operation
3+
metadata:
4+
name: update-user-validation-for-critical-xr-once
5+
spec:
6+
spec:
7+
mode: Pipeline
8+
pipeline:
9+
- step: user-validation
10+
functionRef:
11+
name: function-msgraph
12+
input:
13+
apiVersion: msgraph.fn.crossplane.io/v1alpha1
14+
kind: Input
15+
queryType: UserValidation
16+
# Replace these with actual users in your directory
17+
users:
18+
- "[email protected]"
19+
- "[email protected]"
20+
- "[email protected]"
21+
target: "status.validatedUsers"
22+
credentials:
23+
- name: azure-creds
24+
source: Secret
25+
secretRef:
26+
namespace: upbound-system
27+
name: azure-account-creds
28+
requirements:
29+
requiredResources:
30+
- requirementName: ops.crossplane.io/watched-resource
31+
apiVersion: example.crossplane.io/v1
32+
kind: XR
33+
name: example-xr

‎example/operations/watchoperation.yaml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
apiVersion: ops.crossplane.io/v1alpha1
2+
kind: WatchOperation
3+
metadata:
4+
name: update-user-validation-for-critical-xrs
5+
spec:
6+
watch:
7+
apiVersion: example.crossplane.io/v1
8+
kind: XR
9+
matchLabels:
10+
always-update: "true"
11+
concurrencyPolicy: Allow
12+
operationTemplate:
13+
spec:
14+
mode: Pipeline
15+
pipeline:
16+
- step: user-validation
17+
functionRef:
18+
name: function-msgraph
19+
input:
20+
apiVersion: msgraph.fn.crossplane.io/v1alpha1
21+
kind: Input
22+
queryType: UserValidation
23+
# Replace these with actual users in your directory
24+
users:
25+
- "[email protected]"
26+
- "[email protected]"
27+
- "[email protected]"
28+
target: "status.validatedUsers"
29+
credentials:
30+
- name: azure-creds
31+
source: Secret
32+
secretRef:
33+
namespace: upbound-system
34+
name: azure-account-creds

0 commit comments

Comments
 (0)