From 13b09554610abf19b9db25e1c0d1a6a56efb345f Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Mon, 20 Apr 2026 18:06:48 -0400 Subject: [PATCH 1/2] docs: add per-resource poll interval and reconcile-request annotations Signed-off-by: Yordis Prieto --- .../master/composition/composite-resources.md | 41 ++++++++++ content/master/guides/pods.md | 9 +++ .../managed-resources/managed-resources.md | 78 +++++++++++++++++++ 3 files changed, 128 insertions(+) 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/) From 6eb7b8aaf41dfb5dd86bf32cbd42350bf295c65f Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Tue, 19 May 2026 02:27:13 -0400 Subject: [PATCH 2/2] docs: satisfy vale style checks for poll-interval and reconcile-request docs Signed-off-by: Yordis Prieto --- .../master/composition/composite-resources.md | 2 +- .../managed-resources/managed-resources.md | 21 +++++++++---------- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/content/master/composition/composite-resources.md b/content/master/composition/composite-resources.md index f89ffed17..5e65460b8 100644 --- a/content/master/composition/composite-resources.md +++ b/content/master/composition/composite-resources.md @@ -270,7 +270,7 @@ spec: ### Per-resource poll interval The {{}}crossplane.io/poll-interval{{}} -annotation overrides the controller-level `--poll-interval` for a specific +annotation overrides the default `--poll-interval` for a specific composite resource. The annotation accepts any valid Go duration string. ```yaml {label="xr-poll-interval",copy-lines="none"} diff --git a/content/master/managed-resources/managed-resources.md b/content/master/managed-resources/managed-resources.md index b0e53401d..2b2be4338 100644 --- a/content/master/managed-resources/managed-resources.md +++ b/content/master/managed-resources/managed-resources.md @@ -516,7 +516,7 @@ 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/poll-interval` | Overrides the default 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. | {{}} @@ -751,8 +751,8 @@ for more details. ### 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 +annotation overrides the default `--poll-interval` for a specific +managed resource. Use the annotation 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`, @@ -773,13 +773,12 @@ spec: ``` {{< 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. +Crossplane ignores values that aren't valid Go durations and falls back to +the controller default. The controller raises any value below the +`--min-poll-interval` flag (defaults to `1s`) to the configured minimum. {{< /hint >}} -Remove the annotation to return to the controller-level `--poll-interval` -default. +Remove the annotation to return to the default `--poll-interval`. ### Reconcile request @@ -788,8 +787,8 @@ 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. +Set the annotation to any value, such as a timestamp or unique identifier, to +trigger a reconciliation. ```yaml {label="reconcile-request",copy-lines="none"} apiVersion: rds.aws.m.upbound.io/v1beta1 @@ -806,7 +805,7 @@ spec: ``` The reconciler records the handled token in `status.lastHandledReconcileAt` so -operators can confirm the request was processed. +operators can confirm the controller handled the request. ```shell # Request reconciliation