diff --git a/providers/cncf/kubernetes/docs/operators.rst b/providers/cncf/kubernetes/docs/operators.rst index abdd4307abade..05da87f11dd4e 100644 --- a/providers/cncf/kubernetes/docs/operators.rst +++ b/providers/cncf/kubernetes/docs/operators.rst @@ -220,6 +220,15 @@ Durable execution requires Airflow 3.3 or newer, since it relies on the task sta earlier Airflow versions ``durable=True`` (the default) falls back to the same label-search reattach behavior this operator has always used. +The pod identity persisted in task state store isn't deleted automatically, that only happens +when someone runs ``airflow state-store clean``. If a task's ``retry_delay`` is longer than +``[state_store] default_retention_days`` (30 days by default) and cleanup runs in between, the +pod identity won't be there for the next retry, and the operator falls back to the label-search +bootstrap path instead of reconnecting directly. This isn't necessarily a duplicate, the label +search can often still find the same pod, but it loses the unambiguous reconnect and reopens +exposure to ``FoundMoreThanOnePodFailure`` if a genuine duplicate pod exists by then. Avoid +running cleanup on a schedule shorter than your longest ``retry_delay``. + ``durable`` supersedes the deprecated ``reattach_on_restart`` parameter -- passing ``reattach_on_restart`` still works but emits ``AirflowProviderDeprecationWarning`` (on Airflow 3.3+) and maps its value onto ``durable``.