chore: backport 10/27: add placement policy APIs

.github/.copilot/breadcrumbs/2026-08-12-2353-delete-stage-tasks.md

@@ -0,0 +1,42 @@
+# Support Before-Stage Tasks on the Delete Stage
+
+## Overview
+
+Allow staged update strategies to gate the delete stage with an Approval task, the same before-stage task the
+update stages support, so that removing the resources from the clusters that left a placement can be held until
+a sign-off is given.
+
+## Plan
+
+1. Add an optional `deleteStage` to the shared update strategy API, with `beforeStageTasks`.
+2. Snapshot the tasks and initialize their statuses as the `beforeStageTaskStatus` of the delete stage.
+3. Evaluate the tasks with the same code that evaluates the before-stage tasks of the update stages.
+4. Add API validation, unit, integration and E2E coverage for both cluster-scoped and namespaced runs.
+5. Regenerate API code and CRDs, then run the tests and the repository quality checks.
+
+## Decisions
+
+- The delete stage is configured as a stage (`deleteStage.beforeStageTasks`) rather than with a delete stage
+  specific task list, so that the API, the status and the approval requests use the same vocabulary as the
+  update stages, and so that the delete stage can take more configurations later.
+- The before-stage tasks of the delete stage follow the update stages: at most one task, and it must be an
+  Approval. A soak time before the removal is already possible with a TimedWait in the afterStageTasks of the
+  last update stage, as the delete stage only starts once the last update stage, including its after-stage tasks,
+  completes.
+- The approval request is named `<updateRun>-before-delete-stage` with the generic before-stage name format.
+  `delete-stage` also is the stage label value of the approval request, as the name of the delete stage,
+  `kubernetes-fleet.io/deleteStage`, is not a valid label value. An update stage cannot have this name.
+- The tasks only gate the start of the deletion and they are skipped if there is no cluster to delete, the same
+  as an update stage with no clusters.
+- An update run that is stopped while it waits for the tasks stops without deleting any binding.
+
+## Success Criteria
+
+- [x] No delete stage configuration preserves immediate deletion.
+- [x] The approval must be given before any binding is deleted.
+- [x] Cluster-scoped and namespaced runs keep the bindings until the tasks pass.
+- [x] Generated API and CRD artifacts are current.
+
+## Follow-ups
+
+- Document the delete stage configuration in the staged update docs (website repository).

.github/.copilot/breadcrumbs/2026-09-10-0000-cleanup-leftover-works.md

@@ -0,0 +1,32 @@
+# Cleanup Leftover Works
+
+## Goal
+
+Implement `cleanupLeftOverWorks` so manifests previously applied or prepared by leftover Work objects are removed unless still referenced by the current linked Work set.
+
+## Plan
+
+- [x] Collect manifest identifiers whose Applied condition is true or has the preparing-to-process reason.
+- [x] Exclude identifiers present in `seenManifIDs`.
+- [x] Remove the collected manifests in parallel through `removeOneLeftOverManifest`.
+- [x] Aggregate per-manifest failures and run focused validation.
+
+## Success Criteria
+
+- Current manifests are preserved.
+- Only previously applied or pre-processed leftover manifests are selected.
+- Selected manifests are removed through the existing ownership-aware helper in one parallel batch.
+
+## Validation
+
+- `gofmt` completed successfully.
+- Editor diagnostics report no errors in `cleanup.go`.
+- `go test ./pkg/v1/controllers/workapplier` is currently blocked by pre-existing unused `leftOverWorks` and `seenManifestIDs` variables in `controller.go`, where the surrounding cleanup call site is still unfinished.
+
+## Placement Deletion Follow-Up
+
+- [ ] Preserve explicit sync strategy values while applying defaults.
+- [ ] Delete linked AppliedWork objects with foreground or orphan propagation according to `WhenPlacementDeleted`.
+- [ ] After `foregroundDeletionWaitTime`, explicitly clean tracked manifests blocking foreground deletion.
+- [ ] Remove Work cleanup finalizers only after the corresponding AppliedWork is gone.
+- [ ] Wire placement and leftover cleanup into reconciliation and validate the package.

.github/.copilot/breadcrumbs/2026-09-23-1617-hub-condition-timestamp.md

@@ -0,0 +1,26 @@
+# Fix: Preserve UpdateRun Condition Transition Timestamp
+
+## Overview
+
+Prevent hub-agent reconciliation and restarts from restamping the UpdateRun status metric when the selected Kubernetes condition has not transitioned.
+
+## Plan
+
+1. Trace UpdateRun condition reconciliation and metric emission.
+2. Emit the selected condition's persisted `LastTransitionTime` instead of reconciliation time.
+3. Add focused unit tests for unchanged failed conditions and actual status transitions.
+4. Run the smallest relevant UpdateRun unit test suite.
+
+## Success Criteria
+
+- [x] Re-emitting an unchanged failed condition preserves the metric timestamp.
+- [x] A condition status transition emits the new transition timestamp.
+- [x] Focused UpdateRun tests pass.
+
+## Implementation Notes
+
+- Kubernetes `meta.SetStatusCondition` already preserves `LastTransitionTime` when `Status` is unchanged and advances it when `Status` changes.
+- The restamping occurred in metric emission through `SetToCurrentTime()`, independently of the persisted condition.
+- `emitUpdateRunStatusMetric` now sets the gauge from the selected condition's `LastTransitionTime`.
+- Added table-driven unit coverage for failed, initialized, executing, and succeeded runs. Each case emits twice to prove reconciliation does not restamp the selected condition's timestamp.
+- Validation: `go test ./pkg/controllers/updaterun -run 'TestEmitUpdateRunStatusMetricUsesConditionTransitionTime|TestDetermineFailureType|TestIsFailureReason' -count=1`.

.github/.copilot/breadcrumbs/2026-10-02-0001-add-work-owner-binding-field-index.md

@@ -0,0 +1,39 @@
+# Add Work Owner Binding Field Index
+
+**Date**: October 2, 2026 00:01 AEST
+**Task**: Add a composite field index for Work objects keyed by owner binding namespace and name.
+
+## Requirements
+
+1. Add the `workOwnedByBinding` custom field.
+2. Format indexed values as `%s/%s`.
+3. Extract the owner namespace from `WorkOwnerNamespaceLabelKey`.
+4. Extract the owner binding name from `WorkOwnedByPlacementBindingLabelKey`.
+5. Register the Work field extractor in `SetupWithHubControllerManager`.
+6. Use the custom field index when listing Work objects by owner binding.
+7. Use the existing owner-and-index custom field when listing secondary placement resource snapshots.
+
+## Plan
+
+1. Add exported field-name and value-format constants to `pkg/v1/utils/fieldindexers/hub.go`.
+2. Add a Work owner-binding field extractor using the owner namespace and binding labels, while distinguishing a missing owner-namespace label from a valid empty cluster-scoped namespace.
+3. Register the extractor for `placementv1alpha1.Work` in `SetupWithHubControllerManager`.
+4. Update `listWorksByOwnerBinding` to query the composite custom field while retaining the Work namespace filter.
+5. Update secondary placement resource snapshot retrieval to query the existing composite owner-and-index field.
+6. Run the targeted field-indexer and workgenerator package tests and formatting.
+
+## Decisions
+
+1. Use the owner-binding label as the indexed binding-name source.
+2. Permit an empty owner namespace only when the owner-namespace label is present, preserving support for cluster-scoped bindings.
+3. Unit tests are omitted for now at the user's request.
+
+## Status
+
+Implementation complete.
+
+## Validation
+
+- `gofmt -w pkg/v1/utils/fieldindexers/hub.go pkg/v1/controllers/workgenerator/retrieval.go`
+- `go test ./pkg/v1/utils/fieldindexers ./pkg/v1/controllers/workgenerator` (passed; packages currently have no test files)
+- `git diff --check` (passed)

.github/.copilot/breadcrumbs/2026-10-08-1729-selected-resource-authorization.md

@@ -0,0 +1,165 @@
+# Enforce selected-resource authorization
+
+**Date**: October 8, 2026 17:29 UTC
+**Task**: Prevent placement and override APIs from using Fleet's controller permissions to access resources the requester could not access directly.
+
+## Requirements
+
+1. Enforce selected-resource authorization for ClusterResourcePlacement, ResourcePlacement, ClusterResourceOverride, and ResourceOverride create and update requests.
+2. Build SubjectAccessReview requests from the admission request's complete user information: username, UID, groups, and extras.
+3. Fail closed when resource resolution or authorization cannot be completed.
+4. Require `get` for resources selected by name.
+5. For CRP/RP label and all-of-kind selectors, require `list` in the relevant scope, without individual `get` checks for enumerated objects.
+6. For namespace selection, authorize the Namespace selection using `get` by name or `list` for label/all-of-kind selection. For NamespaceWithResources, require `list` per eligible expanded namespaced resource type, without individual `get` checks for their objects.
+7. Ignore resources that begin matching dynamic selectors after admission in this implementation.
+8. Require `patch` for JSONPatch overrides and `delete` for Delete overrides.
+9. Require Kubernetes RBAC privilege-protection checks when overrides affect Role, ClusterRole, RoleBinding, or ClusterRoleBinding resources.
+10. For CRP/RP, authorize creates and reauthorize the complete selected set on spec-changing updates, even if selectors are unchanged. Overrides retain the original every-update reauthorization requirement.
+11. For CRP/RP, skip selected-resource authorization on updates with semantically unchanged specs, including label, annotation, and finalizer changes regardless of deletion state. Preserve existing validation behavior. For overrides, retain the deletion/finalizer cleanup exception.
+12. Enable enforcement by default and provide a temporary feature flag to disable it.
+
+## Plan
+
+### Phase 1: Authorization foundation and tests
+
+- [x] Add a selected-resource reviewer that creates Kubernetes SubjectAccessReviews and preserves all admission user information.
+- [x] Add RESTMapper-based conversion from selector GVKs to the plural GVRs required by SubjectAccessReview.
+- [x] Deduplicate identical checks within one authorization batch and use bounded concurrency for object-level reviews.
+- [x] Add unit tests for allowed, denied, no-opinion, API-error, timeout, identity-copying, and duplicate-review cases.
+- **Success criterion:** Authorization behavior is independently testable and every unresolved or unsuccessful review fails closed.
+
+### Phase 2a: ResourcePlacement authorization (current slice)
+
+- [x] Build RP permission checks from selectors and REST mappings without fetching source objects.
+- [x] Require `get` for named selections and `list` for label/all-of-kind selections in the RP namespace.
+- [x] Authorize creates and spec-changing updates; preserve existing validation and deletion cleanup behavior.
+- [x] Add RP constructor, scope, selector, overlapping-review, identity, denial, and failure tests.
+- **Success criterion:** RP authorization is independently testable, fails closed, and does not require live object or informer dependencies.
+
+### Phase 2b: ClusterResourcePlacement authorization (follow-up slice)
+
+- [ ] Add direct cluster-scoped resource authorization.
+- [ ] Resolve selected Namespaces using live hub API reads.
+- [ ] Add NamespaceOnly, NamespaceWithResourceSelectors, and NamespaceWithResources authorization.
+- [ ] Add CRP webhook tests for namespace modes, scope, overlapping selectors, and failure cases.
+- **Success criterion:** CRP authorization follows the agreed get/list policy without expanding the RP-only review scope.
+
+### Phase 3: Override authorization
+
+- [ ] Authorize every currently selected CRO and RO target.
+- [ ] Require `patch` for JSONPatch rules, including `remove` operations on fields, and `delete` when a Delete rule removes the entire selected resource from a member cluster.
+- [ ] Apply or inspect override patches sufficiently to perform correct `escalate` checks for Role/ClusterRole rule changes and `bind` checks against the resulting RoleBinding/ClusterRoleBinding role reference.
+- [ ] Add CRO and RO webhook tests for patch, delete, escalate, bind, namespaced scope, update reauthorization, and fail-closed behavior.
+- **Success criterion:** Overrides cannot mutate, suppress, escalate, or bind selected RBAC resources beyond the requester's direct authority.
+
+### Phase 4: Wiring, RBAC, and rollout
+
+- [ ] Add a default-enabled hub-agent feature flag that can temporarily disable selected-resource authorization.
+- [ ] Pass the RESTMapper, uncached/live resource reader, and SAR client into all four validating webhooks.
+- [ ] Grant the hub-agent service account `create` on `authorization.k8s.io/subjectaccessreviews`.
+- [ ] Update directly related Helm values and user-facing flag documentation.
+- **Success criterion:** Default installations enforce authorization, while operators have an explicit temporary rollback switch.
+
+### Phase 5: Verification
+
+- [ ] Run formatting and focused authorization, webhook, and option tests.
+- [ ] Run the smallest relevant integration tests using real Kubernetes RBAC authorization.
+- [ ] Add focused RP webhook authorization wiring and update-gating coverage.
+- [ ] Run `make reviewable` before submission.
+- [ ] Update this breadcrumb with implementation details, changed files, and validation results.
+- **Success criterion:** Focused and repository-required checks pass with no authorization bypass or unrelated behavior regression.
+
+## Decisions
+
+1. Cover all four v1beta1 APIs in separate reviewable slices: RP first, then CRP, CRO, and RO.
+2. Dynamic resources that match after admission are an acknowledged limitation and are not blocked because dynamic selection is a core Fleet feature.
+3. Placement label and all-of-kind selection requires `list` only. Named selection requires `get` for the named object.
+4. NamespaceWithResources authorizes the Namespace selection and requires `list` for each relevant namespaced GVR, without individual `get` checks for enumerated objects.
+5. Delete overrides require `delete`; JSONPatch overrides require `patch`.
+6. CRP/RP creates and spec-changing updates authorize the complete selected set using the current requester's identity. Unchanged-spec updates skip selected-resource authorization but still undergo existing validation. Override updates retain every-update reauthorization.
+7. Finalizer removal during deletion bypasses selected-resource authorization.
+8. Enforcement is enabled by default behind a temporary disable flag.
+
+## Non-goals
+
+1. Continuous reauthorization when a new resource begins matching an existing dynamic selector.
+2. Persisting creator identity for controller-time authorization.
+3. Replacing Kubernetes RBAC or supporting label-restricted authorization policies beyond what SubjectAccessReview reports.
+
+## Status
+
+Plan approved by the user. Phase 1 and the Phase 2a RP-only slice are complete on
+`feat/selected-resource-authorization-phase-2`. Phase 2b and Phases 3-5 remain.
+On October 19, the user requested a smaller review scope. The full implementation
+is preserved in pushed commit `e640d9b2`; the follow-up slice retains RP only.
+
+## Phase 2a implementation details
+
+- Added `ResourcePlacementAuthorizer` and `NewResourcePlacementAuthorizer` in
+  `pkg/utils/authorization/placement.go`, with private mapper, reviewer, and
+  eligibility-checker dependencies. No reader, informer, or Namespace resolution
+  is needed. An explicit RP/CRP type switch routes RP to its typed resolver;
+  the CRP branch returns a clear not-implemented error for the follow-up slice.
+- Build get checks for named selectors and list checks for label/all-of-kind
+  selectors in the RP namespace. No source objects are fetched. Reuse the Phase 1
+  reviewer's identity preservation, deduplication, and bounded concurrency.
+- Use explicit Allowed, Denied, and Indeterminate decisions. Denials take
+  precedence over additional review errors; malformed results fail closed.
+- Add an optional RP webhook authorizer through shared placement validation.
+  Authorize creates and spec-changing updates only. Unchanged-spec updates still
+  run existing validation, and the old invalid-placement deletion exception is
+  unchanged. Authorizer unit tests cover scope, selectors, denials, and SAR errors;
+  shared validator tests cover admission decision mapping. The dedicated RP
+  webhook authorization test file was removed at the user's request; its wiring
+  and update-gating coverage is deferred.
+- Defer CRP authorization and its tests. Its handler passes nil to the shared
+  authorization parameter, preserving existing behavior. The controller's resource
+  selector resolver is unchanged.
+- Production registration still does not inject the RP authorizer. Default-on
+  enforcement, rollout wiring, and SAR RBAC remain Phase 4.
+
+## Phase 2a validation
+
+- Focused race tests passed for `pkg/utils/authorization`, `pkg/utils/validator`,
+  `pkg/webhook/clusterresourceplacement`, and `pkg/webhook/resourceplacement`.
+- Existing CRP webhook tests passed unchanged.
+- `go vet` passed for the authorization, validator, and placement webhook packages.
+- `go build ./cmd/hubagent/...` passed.
+- Before committing, `make lint GOLANGCI_LINT=/home/weiweng/go/bin/golangci-lint`
+  passed repository-wide with the installed repository-version linter (v2.13.2).
+- Repository-configured lint passed with `--new-from-rev=main`,
+  `--max-issues-per-linter=0`, and `--max-same-issues=0` for the affected packages.
+  Unfiltered package lint also reports pre-existing issues in the CRP mutating
+  webhook tests; these were not changed.
+- `git diff --check` passed. Go commands use
+  `MS_GOTOOLCHAIN_ALLOW_NON_LOCAL=1 GOTOOLCHAIN=auto`, as in Phase 1.
+- Full `make reviewable` and real Kubernetes RBAC integration remain Phase 5
+  verification, before PR submission.
+
+## Phase 1 implementation details
+
+- Added `pkg/utils/authorization` with a reusable, stateless batch Reviewer.
+- Preserved username, UID, groups, and deep-copied extras in every SubjectAccessReview.
+- Added RESTMapper-based GVK-to-GVR conversion for correctly pluralized authorization attributes.
+- Deduplicated identical attributes within each authorization batch; separate calls always perform fresh reviews.
+- Limited concurrent SubjectAccessReviews per request, collected results in stable input order, and recorded explicit failures for reviews not submitted after request cancellation.
+- Returned structured results that aggregate explicit denials separately from joined evaluation, API, and malformed-response errors; conclusive denials take precedence while errors remain available for logging.
+- Added focused unit coverage for resource mapping, identity propagation, aggregated denial and error results, timeout handling, deduplication, and bounded concurrency.
+
+## Phase 1 validation
+
+- `MS_GOTOOLCHAIN_ALLOW_NON_LOCAL=1 GOTOOLCHAIN=auto go test -race ./pkg/utils/authorization` passed.
+- `MS_GOTOOLCHAIN_ALLOW_NON_LOCAL=1 GOTOOLCHAIN=auto go vet ./pkg/utils/authorization` passed.
+- Automatic toolchain selection was required because `go.mod` requires Go 1.26.6 while the installed local Microsoft Go toolchain is 1.26.5.
+
+## References
+
+- `pkg/utils/validator/placement.go` - shared CRP/RP admission validation.
+- `pkg/webhook/clusterresourceplacement` - CRP mutating and validating webhooks.
+- `pkg/webhook/resourceplacement` - RP validating webhook.
+- `pkg/webhook/clusterresourceoverride` - CRO validating webhook.
+- `pkg/webhook/resourceoverride` - RO validating webhook.
+- `pkg/utils/controller/resource_selector_resolver.go` - current placement selector resolution semantics.
+- `cmd/hubagent/options/featureflags.go` - hub-agent feature flag conventions.
+- `charts/hub-agent/templates/rbac.yaml` - hub-agent service account permissions.
+- No applicable specification directory exists under `.github/.copilot/`, and no selected-resource authorization entry was found in the domain knowledge files.