Add delete_pods_in_phase override to KubernetesPodOperator

[SameerMesiah97]

Description

This change introduces a new optional parameter, delete_pods_in_phase, to KubernetesPodOperator that allows pod deletion to be controlled explicitly by Kubernetes pod phase.

When delete_pods_in_phase is provided, the operator deletes a pod only if its current phase matches one of the configured values. In this mode, pod deletion is determined solely by phase and takes precedence over on_finish_action. This behavior is applied consistently across all pod-cleanup paths, including normal execution, failure handling, and duplicate-label pod resolution.

When the override is enabled, the operator emits an informational log message during initialization to make the precedence over on_finish_action explicit in task logs.

Rationale

Recent changes to on_finish_action have introduced or proposed additional pod-deletion modes, such as delete_active_pod (PR #59160) and delete_non_failed_pod (PR #59413), to support more nuanced cleanup behavior.

Rather than continuing to add new high-level on_finish_action values for each possible combination of pod phases, this change introduces a more general and explicit mechanism for advanced users. The delete_pods_in_phase parameter allows users to specify exactly which Kubernetes pod phases should trigger deletion, avoiding ambiguity and removing the need to debate or encode specific phase combinations into new modes.

This approach maximizes configurability while preserving existing semantics and keeping default behavior unchanged.

Documentation

A docstring has been added to process_pod_deletion describing the deletion decision flow and documenting the precedence of delete_pods_in_phase over on_finish_action.

Notes

• Patching logic has been made more explicit to reflect whether a pod was intentionally retained due to phase-based deletion rules.
• Duplicate-label pod handling has been updated to respect delete_pods_in_phase, ensuring consistent cleanup behavior when multiple pods share identical task labels.

Tests

Added unit tests that:

• Verify that delete_pods_in_phase overrides on_finish_action when determining whether a pod should be deleted.
• Update existing cleanup tests to cover phase-based deletion and patching behavior when deletion does not occur.
• Validate input normalization and error handling for delete_pods_in_phase values.

Backwards Compatibility

When delete_pods_in_phase is not provided, pod deletion behavior remains unchanged and continues to be governed exclusively by on_finish_action. No existing defaults are modified, and no public APIs are removed or altered besides the addition of the delete_pods_in_phase parameter.