feature: Support optional propagation of Namespace labels/annotations from KCP workspaces to destination clusters

[ayetealab]

Feature Description

Some operators (notably AWS ACK) rely on namespace annotations to perform Cross-Account Role Mapping (CARM). These annotations define which AWS IAM roles a namespace is permitted to assume, and without them, ACK cannot function correctly in multi-tenant environments.

Today, api-syncagent treats namespaces as “one-and-done”: it only ensures the namespace exists in the destination cluster as a one off "just-in-time" activity. It honours the namespace name transformation pattern defined for a published resource but it does not propagate labels or annotations nor does it perform any ongoing sync. As a result, key namespace metadata that could be added inside a kcp workspace, and would required by controllers like ACK, is lost.

We have considered alternatives for getting the annotations onto destination namespace, such as admission webhooks or custom controller logic in the destination clusters, but it seems reasonable to also support this use case directly in the api-syncagent via the existing namespace creation flow.

Proposed Solution

• I have prepared a draft PR that demonstrates one possible implementation in the api-syncagent: Adding logic to allow namespace metadata to be honoured on destination #98
• This PR passes unit tests, builds successfully, and when deployed behaves as expected.
• Default behavior remains unchanged (namespaces created with no metadata).
• If the APIExport + APIBinding include permissionClaims for namespaces, the api-syncagent will read upstream source namespace metadata and apply labels/annotations at creation time to the destination namespace.
• If metadata cannot be fetched (forbidden, no claim, etc.), the api-syncagent will log a warning and continue without failing.
• This does not attempt to fully sync namespaces as first-class resources — metadata is only applied at initial creation.

Alternative Solutions

We have considered some alternatives. For example, using an admission webhook on the destination clusters to inject annotations at namespace creation time, or layering custom logic outside of the api-syncagent to maintain the metadata. While technically possible, such approaches introduce additional moving parts, require external sources of truth, and duplicate functionality that might more cleanly be achieved during the sync-agent’s existing namespace creation process.

Therefore, it seems reasonable to explore extending the current namespace creation process in api-syncagent to optionally propagate namespace metadata when the upstream APIExport and APIBinding allow it. That said, we welcome alternative ideas and inputs from the community.

Want to contribute?

• I would like to work on this issue.

Additional Context

No response