sync: support configurable deletion propagation

[sudo-amine]

Summary

The Sync Agent currently uses background propagation when deleting synchronized
objects from the service cluster. Consequently, foreground and orphan
deletion policies cannot be reflected from kcp side to individual service-cluster copies.

The propagation policy from a kcp DELETE request is not persisted as object
state that the Sync Agent can reliably consume. This change therefore reads the
syncagent.kcp.io/deletion-propagation-policy annotation from the kcp source
object and applies the selected policy when deleting the service-cluster copy.

Supported values are background, foreground, and orphan. Missing or
unsupported values preserve the existing background behavior. The annotation
is not copied to the service-cluster object.

Kcp-origin related resources resolve the policy from their own source object.
Service-origin related resources retain their existing behavior.

Design rationale

Several alternatives were considered:

• Inferring the policy from the kcp object after DELETE is not reliable. The
  DeleteOptions.PropagationPolicy value is not persisted on the object, and
  garbage-collection finalizers are not a durable signal for every policy.
• A deterministic handshake could keep synchronized objects observable during
  deletion, but it would require changes in the generic kcp storage deletion
  path to capture and persist the DELETE option. This would couple low-level
  kcp storage behavior to a Sync Agent-specific protocol, while also requiring
  finalizer rollout and lifecycle management on existing objects.
• An admission-based capture mechanism would add cluster-level configuration,
  permissions, deployment lifecycle, and ownership concerns, especially when
  several agents share the same API source.
• Extending PublishedResource would introduce an API change while still being
  poorly suited to a policy selected for an individual object.

The annotation approach is intentionally narrow and explicit. It stores the
policy on the source object where it remains observable until cleanup, requires
no API, storage, or admission changes, and does not modify the existing
finalizer lifecycle.

What Type of PR Is This?

/kind feature

Related Issue(s)

Addresses #174

Validation

• make imports
• make test
• Documentation updated
• E2e compilation
• Focused e2e tests:
  • TestPrimaryDeletionPropagationPolicy
  • TestKcpRelatedCleanupUsesItsOwnDeletionPropagationPolicy

Release Notes

The Sync Agent now supports the `syncagent.kcp.io/deletion-propagation-policy`
annotation for background, foreground, or orphan deletion of synchronized
objects and kcp-origin related resources.

[kcp-ci-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign embik for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[kcp-ci-bot]

Hi @sudo-amine. Thanks for your PR.

I'm waiting for a kcp-dev member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.