Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -386,6 +386,7 @@ spec:
| `servicePrincipalsRef` | string | Reference to resolve a list of service principal names from `spec`, `status` or `context` (e.g., `spec.servicePrincipalConfig.names`) |
| `target` | string | Required. Where to store the query results. Can be `status.<field>` or `context.<field>` |
| `skipQueryWhenTargetHasData` | bool | Optional. When true, will skip the query if the target already has data |
| `skipQueryWhenRefMissing` | bool | Optional. When true, a `groupRef`, `groupsRef`, `usersRef` or `servicePrincipalsRef` whose path does not exist yet skips the query with a warning instead of failing the pipeline. The target is left untouched. Default is false. See [Skipping when a reference is not resolvable yet](#skipping-when-a-reference-is-not-resolvable-yet). |
| `queryInterval` | string | Optional. Minimum interval between queries as a Go duration string (e.g. `10m`, `1h`, `90s`). Skips querying Microsoft Graph until the interval has elapsed since the last successful query, independent of reconcile frequency. Only effective in Composition mode with a `status.` target. |
| `failOnEmpty` | bool | Optional. When true, the function will fail if the `users`, `groups`, or `servicePrincipals` lists are empty, or if their respective reference fields are empty lists. |
| `activeAccount` | bool | Optional. `UserValidation` only. When true, only users whose Entra ID `accountEnabled` attribute is true are stored at the target; disabled users, and users whose account state Graph does not report, are omitted. |
Expand Down Expand Up @@ -509,6 +510,45 @@ servicePrincipalsRef: "spec.servicePrincipalConfig.names" # Get service princip
target: "status.servicePrincipals"
```

### Skipping when a reference is not resolvable yet

By default, a reference whose path does not exist is a fatal error, which aborts
the whole Composition pipeline. That can deadlock an XR when the referenced field
is written later in the pipeline or on a later reconcile, for example when a
later step creates the Entra ID group and records its name in the XR status.

Set `skipQueryWhenRefMissing: true` to skip the query instead:

```yaml
apiVersion: msgraph.fn.crossplane.io/v1alpha1
kind: Input
queryType: GroupMembership
groupRef: "status.groups.owners.name" # Written by a later step once the group exists
target: "status.ownerMembers"
skipQueryWhenRefMissing: true
```

While the path is missing, the function does not call Microsoft Graph, leaves the
target and its `lastQueryTimestamps` entry untouched, passes the desired XR and
context through unchanged, emits a Warning result and sets a `FunctionSkip`
condition with reason `RefNotResolved`. The rest of the pipeline runs, and the
query runs on the first reconcile where the reference resolves. In Operation
mode, a skipped run does not update the drift annotations.

> Note: a `status.` reference is read from the desired XR status when an earlier
> pipeline step has written any status, and from the observed XR otherwise. If an
> earlier step writes status, the referenced field must be in that desired status
> (for example by carrying it over from the observed XR); a field present only on
> the observed XR is not read, so the query keeps being skipped.

Only a missing path is skipped. These remain fatal even with the flag set:

- an unsupported reference (for example one that does not start with
`spec.`, `status.` or `context.`)
- a path that exists but holds the wrong type (not a map, not a string array, or
a non-string value for `groupRef`)
- any Microsoft Graph error, including a group that does not exist

## Using data from EnvironmentConfig

To use data from a Crossplane `EnvironmentConfig`, first load the data into the context using [function-environment-configs](https://github.com/crossplane-contrib/function-environment-configs). This function should be in the pipeline before you use function-msgraph.
Expand Down
10 changes: 10 additions & 0 deletions example/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,3 +157,13 @@ crossplane render xr.yaml user-validation-example.yaml functions.yaml --function
```

> The example intentionally omits `skipQueryWhenTargetHasData`. Enabling `activeAccount` on an XR whose target already holds disabled users does not purge them while the query is being skipped, so clear the target once (or drop the skip for one reconcile) when adopting the flag on an existing deployment.

### 7. Skip When a Reference Is Missing

With `skipQueryWhenRefMissing: true`, a reference whose path does not exist yet skips the query instead of failing the pipeline. `xr.yaml` has no `status.ownersGroup.name`, so the render below emits a Warning result and a `FunctionSkip`/`RefNotResolved` condition, makes no Graph call and leaves `status.ownerMembers` unset:

```shell
crossplane render xr.yaml group-membership-example-skip-ref-missing.yaml functions.yaml --function-credentials=./secrets/azure-creds.yaml -r
```

Remove `skipQueryWhenRefMissing` from the example to see the default, fatal `cannot resolve groupRef: status.ownersGroup.name not found`.
28 changes: 28 additions & 0 deletions example/group-membership-example-skip-ref-missing.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
apiVersion: apiextensions.crossplane.io/v1
kind: Composition
metadata:
name: group-membership-example-skip-ref-missing
spec:
compositeTypeRef:
apiVersion: example.crossplane.io/v1
kind: XR
mode: Pipeline
pipeline:
- step: get-owner-members
functionRef:
name: function-msgraph
input:
apiVersion: msgraph.fn.crossplane.io/v1alpha1
kind: Input
queryType: GroupMembership
# Written to the XR status by a later step once the group exists.
groupRef: status.ownersGroup.name
target: "status.ownerMembers"
# Skip (with a warning) instead of failing while the reference is missing.
skipQueryWhenRefMissing: true
credentials:
- name: azure-creds
source: Secret
secretRef:
namespace: crossplane-system
name: azure-account-creds
Loading
Loading