feat: propagate Crossplane default labels and user metadata to all Cloud Foundry resources

[gergely-szabo-sap]

Summary

Adds automatic propagation of Crossplane default labels (crossplane-kind, crossplane-name, crossplane-provider-config) and user-specified metadata (labels/annotations) to all Cloud Foundry resources managed by the provider.

Default Crossplane labels

When a managed CF resource is created or updated, the provider automatically applies
Crossplane-recommended labels from resource.GetExternalTags() (crossplane-runtime
v1.20.0). These are:

Label	Value	Source
crossplane-kind	. (e.g. app.cloudfoundry.crossplane.io)	CR's GroupVersionKind
crossplane-name	CR's .metadata.name (e.g. my-app)	CR's name
crossplane-providerconfig	ProviderConfig name	CR's .spec.providerConfigRef.name (only when set)

Where they appear:

• On the CF resource itself — visible via cf curl /v3/apps/ in the metadata.labels field, or any CF API client that reads resource metadata.
• In the CR's status.atProvider.labels — populated on every Observe cycle from the CF API read-back.

How behavior changes:

• Before this feature: CF resources created by the provider carried no Crossplane-identifying labels. There was no way to tell from the CF side that a resource was managed by Crossplane. Metadata drift was only checked for ServiceRouteBinding (using exact-map equality); all other resources ignored labels/annotations entirely.
• After: Every Create and Update call merges default Crossplane labels into the resource's metadata alongside any user-specified labels. IsUpToDate in all 8 metadata-capable clients now checks metadata drift using subset semantics — it verifies that every desired label/annotation is present and correct in the actual resource, but ignores extra labels on the CF side that the provider didn't set. This prevents drift loops when the CF platform or other actors add labels the provider didn't ask for.

Backward compatibility:

• Existing managed resources will receive the default labels on their next Update cycle after the provider upgrade. The controller detects the missing labels via IsMetadataUpToDate, triggers an Update, and the labels are applied. No manual intervention is needed — this is a one-time migration.
• No CR spec changes — default labels are stripped by LateInitialize before writing into spec.forProvider.labels, so existing CRs remain unchanged.
• No drift loops — the subset-check semantics mean labels added to the CF resource by the platform, other actors, or prior manual configuration will not cause the provider to attempt removal. The provider only asserts that its own desired labels are present; it does not enforce label exclusivity.
• Export portability — the exporter strips default labels from exported CR manifests, since crossplane-kind/crossplane-name/crossplane-providerconfig are environment-specific and must be regenerated by the target controller at the destination.
• Upgrade test coverage verifies that default labels are absent before upgrade and present after (see [BUG] Upgrade test framework does not support single-image provider build #279).

Resources without metadata support:

Six CF resource types (OrgQuota, SpaceQuota, OrgRole, SpaceRole, OrgMembers, SpaceMembers) do not support metadata in the CF API. These are excluded from label/annotation propagation — the ResourceMetadata struct is not embedded in their CRD types, and no metadata drift detection is performed.

Changes

Shared metadata infrastructure

• internal/clients/metadata/ — new shared package providing:
  • BuildMetadata — merges Crossplane default labels with user-specified metadata
  • IsMetadataUpToDate — subset-aware drift detection (desired ⊆ actual)
  • DiffMetadata — produces the minimal merge-patch needed to align actual with desired
  • Nil pointer semantics for label/annotation deletion via the CF API

Resource metadata consolidation

• apis/resources/v1alpha1/resource.go — introduces ResourceMetadata{ Labels, Annotations } struct with json:",inline" embedding
• All 7 CRD types (App, Domain, Org, Space, Route, ServiceInstance, ServiceRouteBinding) now embed ResourceMetadata in both Parameters (spec) and Observation (status)
• CRD YAML manifests regenerated
• DeepCopy functions regenerated

Client and controller wiring

• All 10 resource clients (app, domain, org, space, route, serviceinstance, servicebinding, serviceplan, serviceroutebinding) pass the managed resource through to BuildMetadata on Create and Update
• Metadata read-back from CF API populated into Observation.Labels / Observation.Annotations
• IsUpToDate in each client now checks metadata drift using subset semantics — extra labels from external actors won't trigger spurious updates

Exporter

• cmd/exporter/cf/metadata/ strips Crossplane default labels (crossplane-kind, crossplane-name, crossplane-provider-config) from exported CR manifests, since these are environment-specific and should be regenerated by the target controller

Route controller refactoring

• Split GetByIDOrSpec into FindRouteBySpec (backwards-compatibility fallback) and GetRouteByGUID (primary reconciliation path) for clearer separation of concerns

Tests

• Unit tests: metadata package has 690 lines of test coverage including subset semantics, deletion markers, and edge cases
• Unit tests: all 10 client packages updated to verify metadata propagation in Create/Update/IsUpToDate paths
• E2e tests: label and annotation assertions for App, Org+Space, ServiceInstance+ServiceCredentialBinding, ServiceRouteBinding
• Upgrade test: verifies Crossplane default labels are absent before upgrade and present after (see [BUG] Upgrade test framework does not support single-image provider build #279)

[mpechkurov]

This PR has been split into 6 smaller, independently reviewable PRs for easier review:

PR	Title	Depends On
#287	[281#1] Shared metadata helpers + API standardization	None
#288	[281#2] Migrate SRB controller to shared metadata package	#287
#289	[281#3] Wire Crossplane default labels into all CF resources (core feature)	#288
#290	[281#4] Strip default labels from exporter	#287
#291	[281#5] Route refactor (split GetByIDOrSpec)	#289
#292	[281#6] Test coverage (unit, e2e, upgrade)	#289

Merge order: #287 → #288 → #289 → #290 → #291 → #292

Each PR builds and passes all tests independently. Please review them in order.

[gergely-szabo-sap]

PR Review Guide: Support External Resource Labeling

Feature Overview

This PR adds two capabilities to the provider:

1. User-specified metadata propagation — Labels and annotations defined in
   spec.forProvider.labels / spec.forProvider.annotations are pushed to the
   Cloud Foundry resource on Create and Update, and drift-detected on Observe.

2. Default Crossplane labels — Every Create and Update call also applies
   three Crossplane-recommended labels (crossplane-kind, crossplane-name,
   crossplane-providerconfig) to the CF resource. These are computed from the
   CR's identity by resource.GetExternalTags() (crossplane-runtime v1.20.0)
   and are NOT stored in the CR's spec.

Before this PR

• CF resources created by the provider carried no Crossplane-identifying
  labels. There was no way to identify a managed resource from the CF side.
• Only ServiceRouteBinding checked metadata drift, and it used exact-map
  equality — any extra label on the CF side caused IsUpToDate: false,
  triggering a spurious Update.
• All other resource types ignored labels/annotations entirely.

After this PR

• All 8 metadata-capable CF resources (App, Domain, Org, Space, Route,
  ServiceInstance, ServiceCredentialBinding, ServiceRouteBinding) propagate
  both user labels/annotations and default Crossplane labels.
• All 8 clients use subset-check semantics for drift detection:
  desired ⊆ actual. Extra labels from the CF platform or other actors are
  ignored — no drift loops.
• 6 resources without CF API metadata support (OrgQuota, SpaceQuota, OrgRole,
  SpaceRole, OrgMembers, SpaceMembers) are excluded entirely.

---

Step-by-Step Walkthrough

Step 1: Shared metadata type — ResourceMetadata

File: apis/resources/v1alpha1/resource.go

type ResourceMetadata struct {
    Annotations map[string]*string `json:"annotations,omitempty"`
    Labels      map[string]*string `json:"labels,omitempty"`
}

This struct is embedded via json:",inline" in both the Parameters (spec) and
Observation (status) of all 8 metadata-capable CRD types. The *string pointer
values are significant: a nil value acts as a deletion marker per CF API
convention.

Step 2: Shared metadata package — internal/clients/metadata/

File: internal/clients/metadata/metadata.go

Five public functions:

Function	Purpose
BuildMetadata(mg, userLabels, userAnnotations)	Merges default Crossplane labels with user metadata into a *cfresource.Metadata for Create/Update calls
IsMetadataUpToDate(desired, desired, actual, actual)	Subset-check: returns true iff every key in desired exists and matches in actual
MetadataMapContains(desired, actual)	Core subset check for a single map — used by IsMetadataUpToDate
MetadataMapEqual(desired, actual)	Exact equality check — kept for test utility, not used in drift detection
DiffMetadata(desired, desired, actual, actual)	Produces a minimal *cfresource.Metadata merge-patch for Update calls
StripDefaultLabels(labels)	Removes crossplane-kind/crossplane-name/crossplane-providerconfig from a label map

Key design decisions:

1. Subset semantics, not exact equality. MetadataMapContains only checks
   that desired keys are present and correct in actual. Extra keys in actual
   are ignored. This is critical because:

   • The CF platform may add its own labels
   • Other actors (humans, CI) may add labels the provider didn't set
   • With exact equality, any extra label → perpetual drift loop

2. BuildMetadata always includes default labels. Even if
   spec.forProvider.labels is empty, BuildMetadata calls
   resource.GetExternalTags(mg) which returns at least crossplane-kind and
   crossplane-name. User labels override defaults on key collision.

3. Nil pointer = deletion marker. In spec.forProvider.labels, a key with
   a nil value means "delete this label from the CF resource on Update."
   BuildMetadata passes these through via m.RemoveLabel().

4. StripDefaultLabels prevents spec pollution. Used in LateInitialize
   and the exporter to strip default labels from maps that will be written into
   spec.forProvider.labels. The controller recomputes these on every
   reconcile — storing them in spec would be semantically incorrect.

Step 3: Client wiring — Create, Update, IsUpToDate

All 8 metadata-capable clients follow the same pattern. Using App as the
representative example:

Create (internal/clients/app/app.go):

appCreate.Metadata = metadata.BuildMetadata(mg, spec.Labels, spec.Annotations)

Update (internal/clients/app/app.go):

appUpdate.Metadata = metadata.BuildMetadata(mg, spec.Labels, spec.Annotations)

IsUpToDate (internal/clients/app/app.go):

desired := metadata.BuildMetadata(mg, spec.Labels, spec.Annotations)
metadataUpToDate := metadata.IsMetadataUpToDate(desired.Labels, desired.Annotations, status.Labels, status.Annotations)
return !changes.HasChanges() && metadataUpToDate, nil

Key observation: All three code paths use BuildMetadata(mg, spec.Labels, spec.Annotations) — the same function produces the desired metadata set. This
ensures consistency: what you create is what you check for drift.

Variations across resources:

Resource	IsUpToDate pattern
App	!changes.HasChanges() && metadataUpToDate
Domain	Metadata-only check (no spec changes)
Org	Short-circuits on spec.Name != observed.Name first
Space	Short-circuits on name/SSH mismatch first
Route	Returns metadata result directly
ServiceInstance	Combined with specUpToDate and credentialsUpToDate
SCB	Metadata-only check
SRB	In controller's handleObservationState, not client IsUpToDate

Step 4: Observation population — reading labels back from CF

Each client's GenerateObservation / UpdateObservation function copies the
CF resource's metadata into the CR's status:

// From internal/clients/space/space.go
if o.Metadata != nil {
    obs.Labels = o.Metadata.Labels
    obs.Annotations = o.Metadata.Annotations
}

This makes labels/annotations visible in status.atProvider.labels and
status.atProvider.annotations.

Step 5: LateInitialize — preventing default label pollution in spec

Only Org currently has a LateInitialize that copies observed labels into
spec.forProvider.labels. It uses StripDefaultLabels:

// From internal/clients/org/org.go
if len(spec.Labels) == 0 && from.Metadata != nil {
    spec.Labels = metadata.StripDefaultLabels(from.Metadata.Labels)
}

Without StripDefaultLabels, the observed default labels (crossplane-kind,
crossplane-name, crossplane-providerconfig) would be copied into
spec.forProvider.labels, which is wrong because:

1. The CR name may change — but the old crossplane-name value would be frozen
   in spec.
2. The controller recomputes these labels on every reconcile from the CR's
   current identity — storing stale values in spec is semantically incorrect.
3. If the CR is exported and re-imported with a different name/ProviderConfig,
   the stale default labels would be applied to the new resource.

Step 6: SRB controller — handleObservationState

The ServiceRouteBinding controller has a unique pattern: its IsUpToDate logic
lives in the controller (not the client), inside handleObservationState. This
is because SRB uses a last-operation state machine instead of a direct
IsUpToDate call.

CF Service Route Bindings are asynchronous-only operations. When you create
or delete an SRB, the CF API doesn't return a synchronous result — it starts a
"last operation" that transitions through Initial → InProgress → Succeeded|Failed.
The SRB controller must inspect binding.LastOperation.State to know whether
the resource is ready, still working, or failed. You can't just call IsUpToDate
unconditionally because:

• If the last operation is InProgress, the resource is still being
  created/deleted — calling IsUpToDate would be meaningless and might trigger
  a redundant Update while the operation is running.
• If the last operation is Failed, the resource is in an error state —
  IsUpToDate is irrelevant until the failure is resolved.
• Only when the last operation is Succeeded does it make sense to ask "is the
  current state matching what I want?"

So the SRB controller uses a state machine (handleObservationState) with a
switch on the last operation state. The metadata drift check only runs inside
the LastOperationSucceeded branch. This is why the check lives in the
controller rather than the client — the decision of when it's safe to check
drift is tightly coupled to the state machine logic.

By contrast, the other 7 resources (App, Domain, Space, etc.) are synchronous —
the controller fetches the CF resource, populates the observation, then calls
client.IsUpToDate(cr, spec, status) as a single function call. Adding metadata
drift detection for those resources meant adding one line to the client's
IsUpToDate.

The LastOperationSucceeded branch now calls BuildMetadata and
IsMetadataUpToDate:

// From internal/controller/serviceroutebinding/controller.go
case v1alpha1.LastOperationSucceeded:
    // ...
    desired := metadata.BuildMetadata(cr, cr.Spec.ForProvider.Labels, cr.Spec.ForProvider.Annotations)
    upToDate := metadata.IsMetadataUpToDate(desired.Labels, desired.Annotations, actualLabels, actualAnnotations)
    return managed.ExternalObservation{ResourceExists: true, ResourceUpToDate: upToDate}, nil

Step 7: Exporter — stripping default labels from exported CRs

File: cmd/exporter/cf/metadata/metadata.go

The exporter strips default Crossplane labels from exported CR manifests. This
is the same StripDefaultLabels logic as in the client package, but lives in
the exporter's own package (no import cycle).

Why: Exported CRs may be imported into a different cluster with a different
name, namespace, or ProviderConfig. The default labels are environment-specific
and must be regenerated by the controller at the destination.

Step 8: Route controller refactoring

The route controller's GetByIDOrSpec was split into:

• FindRouteBySpec(forProvider) — used during adoption (no external name set)
• GetRouteByGUID(guid) — used during normal reconciliation

This is a structural change that was needed because the old combined method
didn't cleanly support the Create/Update metadata wiring. The split makes the
reconciliation paths explicit.

Step 9: Tests

Unit tests (internal/clients/metadata/metadata_test.go):

• MetadataMapContains — subset semantics, nil handling, empty maps
• MetadataMapEqual — exact equality
• DiffMetadata — merge-patch generation
• IsMetadataUpToDate — combined labels+annotations check

Controller tests — all 8 controllers updated:

• args.mg uses withDefaultMetadataLabels() to set GVK (required because
  GetExternalTags uses the GVK to produce crossplane-kind)
• Mock CF resources use .SetLabels(...) with matching default labels
• want.mg also uses withDefaultMetadataLabels() (GVK persists after Observe)
• ResourceUpToDate: true for cases where all conditions (spec + metadata) match
• ResourceUpToDate: false kept for cases with spec mismatches that
  short-circuit before the metadata check

E2e tests (test/e2e/):

• Existing YAML manifests extended with labels and annotations fields
• Existing "ready" assess steps extended with AssertDefaultLabels checks
• No separate label-update test steps — labels are verified inline during the
  normal reconciliation flow

Upgrade test (test/upgrade/label_upgrade_test.go):

• Pre-upgrade: verifies no crossplane-* labels exist on existing resources
• Post-upgrade: verifies all 3 default labels are present with correct values
• Uses CustomUpgradeTestBuilder with custom pre/post assessment functions

---

Backward Compatibility

Scenario	Impact
Existing managed resources	Default labels are applied on next Update cycle after upgrade. No manual intervention needed.
CR spec (spec.forProvider)	Unchanged — LateInitialize strips default labels before writing into spec.
Drift detection	Changed from exact-match (SRB) or none (others) to subset-check. Extra labels on CF resources no longer trigger updates.
Exported CRs	Default labels stripped — safe for import into different environments.
Observe-only resources (managementPolicies: [Observe])	No default labels applied — no impact.

[Kukkerem]

Great work!

[Kukkerem]

Wouldn't this create an infinite loop? DetectChanges only checks the image and name, but if a Label or Annotation changed, HasChanges is false, Update will not call client.Update because in the controller, we have } else if changes.HasChanges() {, and it will do the same in the next reconciliation. Isn't a simple else enough in Update so it always updates when isUpToDate is false?

[Kukkerem]

Org is observe-only I think, so we couldn't reconcile the drift. Do we even need this here? Maybe a simple return spec.Name == observed.Name is enough to at least see if the Org name changed externally.

[Kukkerem]

Shouldn't we implement the same for Space, Domain, App, etc., but skip it for Org because it's observe-only?

[Kukkerem]

Shouldn't we check if we are here because we have set desiredVal to nil - continue if
desiredVal is nil, or every deletion loops.

[Kukkerem]

Shouldn't we return nil when both diffMaps are empty? Why return the Metadata when nothing changed?

[SatabdiG]

Nice work 🔥

[SatabdiG]

if the metadata gets changed, won't it fall through here silently as there is no else block. Won't this creates an infinite reconcile loop: Observe returns ResourceUpToDate: false forever but Update never fixes it.

[SatabdiG]

I noticed that ResourceMetadata is missing // +mapType=granular, wouldn't this be a behaviour regression? Maybe we can add it to the struct's fields?