sync: support configurable deletion propagation

[sudo-amine]

Summary

Today the Sync Agent always deletes a service-cluster copy with background propagation when its kcp source object is deleted. There is no way for a user to request foreground or orphan deletion for an individual object.

This PR lets the kcp source object opt into a different policy via an annotation:

kubectl annotate <resource> <name> \
  syncagent.kcp.io/deletion-propagation-policy=foreground

• Supported values: background, foreground, orphan.
• Missing or unsupported values fall back to background (unchanged default behavior).
• The annotation is not copied to the service-cluster object — it only ever lives on the kcp source.

For related resources, the policy is resolved per-object:

• kcp-origin related resources read the policy from their own annotation, same as the primary object.
• service-origin related resources are unaffected and keep using background.

Design rationale

A few alternatives were considered and rejected:

• Inferring the policy from the kcp DELETE request itself. Kubernetes does not persist DeleteOptions.PropagationPolicy on the object, so there is nothing durable for the Agent to read back later. A deterministic handshake would need changes to kcp's generic storage deletion path to capture and persist that option — coupling low-level kcp storage behavior to an Agent-specific protocol, plus finalizer rollout/lifecycle work on existing objects.
• Capturing the policy via an admission webhook. Adds cluster-level configuration, permissions, and deployment/ownership concerns, especially awkward when multiple agents share the same API source.
• Adding the policy as a field on PublishedResource. Would require an API change, and PublishedResource applies to every object of a kind — a poor fit for a policy that needs to vary per individual object.

The annotation is intentionally narrow and explicit: it stores the policy on the source object where it stays observable until cleanup, requires no API/storage/admission changes, and leaves the existing finalizer lifecycle untouched.

What Type of PR Is This?

/kind feature

Related Issue(s)

Fixes #174

Release Notes

Kcp source objects can now opt into `foreground` or `orphan` deletion propagation for their service-cluster copy via the `syncagent.kcp.io/deletion-propagation-policy` annotation. Defaults to `background` (unchanged).

[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.

[mjudeikis]

This looks ok to me, but I would like @xrstf to check it as he knows this way way better

[mjudeikis]

/ok-to-test

[xrstf]

/approve
/lgtm

[kcp-ci-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: xrstf

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [xrstf]

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]

LGTM label has been added.

Details

Git tree hash: d1d2155f6dbe435ffc93167c234f9202e9a163d1