Proposal: Resource Discovery and Import for Crossplane Providers

Problem

Crossplane providers today can only observe external resources via one-to-one keyed lookup—given an external-name annotation, the provider's Observe() method can fetch and reconcile that resource. However, there is no way to enumerate or discover resources at the provider level.

This blocks two important use cases:

1. Bulk adoption of existing resources: When bootstrapping a new Crossplane cluster, operators often want to adopt existing external resources (e.g., MinIO buckets, RDS instances) that were created by other tools or manually. Currently, this requires hand-writing one manifest per resource—impractical at scale (see #5882: 600+ resources across 10+ accounts).

2. Detection of unmanaged resources: There is no built-in way to identify external resources that exist but have no corresponding Crossplane CR. This is a form of drift distinct from spec-vs-observed drift on existing CRs, and the per-resource poll loop cannot detect it since it only reconciles resources with existing CRs.

Solution Sketch

Define an optional ExternalLister interface in crossplane-runtime that providers may implement to enumerate external resources of a kind:

type ExternalListResult struct {
    ExternalNames []string  // Identifiers suitable for external-name annotation
    NextPageToken string     // For pagination
}

type ExternalLister interface {
    List(ctx context.Context, pc ProviderConfig, pageToken string) (ExternalListResult, error)
}

This enables two consumption paths:

• Path A — One-shot CLI import (crossplane beta import): discover all external resources, diff against existing CRs, emit adoption-ready YAML.
• Path B — Recurring orphan detection (optional controller): periodically list external resources and surface unmanaged ones via Events or a DiscoveryReport CRD.

Both reuse the existing {Observe, LateInitialize} management policy for adoption; no new adoption semantics are needed.

Related Issues

• #1093 — Import existing external resources as managed resources
• #4141 — Support for Querying/Filtering for Import and Observe
• #5882 — Issues with importing resources at scale

Design Document

A full design doc is available in draft PR #7867 with detailed proposal, alternatives, safety/scale considerations, and open questions (DiscoveryReport CRD vs Events, CLI packaging, namespaced-mode interaction).

Questions for Review

• Are there cross-provider patterns or concerns we should bake into the ExternalLister interface before shipping?
• Is the ProviderConfig scoping sufficient for the multi-account/multi-cloud scenarios you see?
• Would a provider need to implement List() differently for different resource kinds, or is a single implementation reasonable?

CC @crossplane/maintainers