diff --git a/content/master/composition/composite-resources.md b/content/master/composition/composite-resources.md index cf93addcc..f89ffed17 100644 --- a/content/master/composition/composite-resources.md +++ b/content/master/composition/composite-resources.md @@ -267,6 +267,47 @@ spec: # Removed for brevity ``` +### Per-resource poll interval + +The {{}}crossplane.io/poll-interval{{}} +annotation overrides the controller-level `--poll-interval` for a specific +composite resource. The annotation accepts any valid Go duration string. + +```yaml {label="xr-poll-interval",copy-lines="none"} +apiVersion: example.org/v1alpha1 +kind: MyDatabase +metadata: + namespace: default + name: my-composite-resource + annotations: + crossplane.io/poll-interval: "24h" +spec: + # Removed for brevity +``` + +Read the [managed resource poll interval annotation]({{}}) for more details on behavior and validation. + +### Triggering immediate reconciliation + +The {{}}crossplane.io/reconcile-requested-at{{}} +annotation triggers an immediate reconciliation when its value changes. Set the +annotation to any value, such as a timestamp, to trigger a reconciliation. + +```yaml {label="xr-reconcile-request",copy-lines="none"} +apiVersion: example.org/v1alpha1 +kind: MyDatabase +metadata: + namespace: default + name: my-composite-resource + annotations: + crossplane.io/reconcile-requested-at: "2024-01-15T10:30:00Z" +spec: + # Removed for brevity +``` + +The reconciler records the handled token in `status.lastHandledReconcileAt`. +Read the [managed resource reconcile request annotation]({{}}) for more details. + ## Verify composite resources Use {{}}kubectl get composite{{}} diff --git a/content/master/guides/pods.md b/content/master/guides/pods.md index 6cfebeaef..3779cf188 100644 --- a/content/master/guides/pods.md +++ b/content/master/guides/pods.md @@ -106,6 +106,15 @@ their `spec`. Managed resources rely on polling to detect changes in the external system. {{< /hint >}} +{{< hint "tip" >}} +To override the poll interval for a specific resource instead of changing the +global setting, use the `crossplane.io/poll-interval` annotation. To trigger an +immediate reconciliation, use the `crossplane.io/reconcile-requested-at` +annotation. Read the +[managed resource annotations]({{}}) +documentation for details. +{{< /hint >}} + Crossplane double-checks all resources to confirm they're in the desired state. Crossplane does this every one hour by default. Use the `--sync-interval` Crossplane pod argument to change this diff --git a/content/master/managed-resources/managed-resources.md b/content/master/managed-resources/managed-resources.md index 279b160f9..b0e53401d 100644 --- a/content/master/managed-resources/managed-resources.md +++ b/content/master/managed-resources/managed-resources.md @@ -516,6 +516,8 @@ resources. | `crossplane.io/external-create-succeeded` | The timestamp of when the Provider successfully created the managed resource. | | `crossplane.io/external-create-failed` | The timestamp of when the Provider failed to create the managed resource. | | `crossplane.io/paused` | Indicates Crossplane isn't reconciling this resource. Read the [Pause Annotation](#paused) for more details. | +| `crossplane.io/poll-interval` | Overrides the controller-level poll interval for this resource. Read the [Poll Interval Annotation](#poll-interval) for more details. | +| `crossplane.io/reconcile-requested-at` | Triggers an immediate reconciliation when its value changes. Read the [Reconcile Request Annotation](#reconcile-request) for more details. | {{}} ### Naming external resources @@ -746,6 +748,82 @@ Read for more details. {{< /hint >}} +### Poll interval + +The {{}}crossplane.io/poll-interval{{}} +annotation overrides the controller-level `--poll-interval` for a specific +managed resource. This is useful when some resources need frequent drift +detection while others are stable and don't need frequent API calls. + +The annotation accepts any valid Go duration string, for example `30m`, `1h`, +or `24h`. + +```yaml {label="poll-interval",copy-lines="none"} +apiVersion: rds.aws.m.upbound.io/v1beta1 +kind: Instance +metadata: + namespace: default + name: my-rds-instance + annotations: + crossplane.io/poll-interval: "24h" +spec: + forProvider: + region: us-west-1 + instanceType: t2.micro +``` + +{{< hint "note" >}} +Invalid values are silently ignored and the controller default is used. +Values below the `--min-poll-interval` flag (defaults to `1s`) are clamped to +the configured minimum. +{{< /hint >}} + +Remove the annotation to return to the controller-level `--poll-interval` +default. + +### Reconcile request + +The {{}}crossplane.io/reconcile-requested-at{{}} +annotation triggers an immediate reconciliation when its value changes. This +follows the pattern established by +[Flux CD's `reconcile.fluxcd.io/requestedAt`](https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.GitRepository). + +Set the annotation to any value, such as a timestamp or UUID, to trigger a +reconciliation. + +```yaml {label="reconcile-request",copy-lines="none"} +apiVersion: rds.aws.m.upbound.io/v1beta1 +kind: Instance +metadata: + namespace: default + name: my-rds-instance + annotations: + crossplane.io/reconcile-requested-at: "2024-01-15T10:30:00Z" +spec: + forProvider: + region: us-west-1 + instanceType: t2.micro +``` + +The reconciler records the handled token in `status.lastHandledReconcileAt` so +operators can confirm the request was processed. + +```shell +# Request reconciliation +kubectl annotate instance my-rds-instance \ + crossplane.io/reconcile-requested-at="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + --overwrite + +# Verify it was handled +kubectl get instance my-rds-instance \ + -o jsonpath='{.status.lastHandledReconcileAt}' +``` + +{{< hint "note" >}} +If the annotation value matches the last handled value, reconciliation isn't +triggered again. +{{< /hint >}} + ## Finalizers Crossplane applies a [Finalizer](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/)