Show only the APIs that make sense for each context

[scotwells]

Summary

When a user runs datumctl api-resources against Milo, they see every API the platform exposes — even the ones that don't apply to where they are. A user browsing their organization sees platform-level APIs mixed in with organization-level ones. A user inside a project sees organization-level APIs they can't act on. It's noise.

This PR lets a resource declare which parent contexts it belongs in (Root, Organization, Project, User), and Milo filters discovery responses accordingly — so datumctl api-resources only shows the APIs that make sense for whatever URL the caller is using.

What the user sees

Before — same list everywhere:

$ datumctl api-resources --api-group=resourcemanager.miloapis.com
NAME                     NAMESPACED   KIND
organizations            false        Organization
organizationmemberships  true         OrganizationMembership
projects                 false        Project

After — scoped to context:

# At the cluster root: just the platform-level APIs
$ datumctl api-resources --api-group=resourcemanager.miloapis.com
NAME             NAMESPACED   KIND
organizations    false        Organization

# Inside an organization: the things you'd do in an org
$ kubectl api-resources --api-group=resourcemanager.miloapis.com  # (org-scoped kubeconfig)
NAME                     NAMESPACED   KIND
organizationmemberships  true         OrganizationMembership
projects                 false        Project

How someone opts a resource in

On a Go-defined type (Milo's own APIs):

// +kubebuilder:metadata:annotations="discovery.miloapis.com/parent-contexts=Organization,User"
type OrganizationMembership struct { ... }

On a CRD installed by an external service building on Milo:

metadata:
  annotations:
    discovery.miloapis.com/parent-contexts: "Organization"

That's the whole contract. No annotation = visible everywhere (so nothing changes until a team opts in). Multiple contexts are comma-separated. Details and the thinking behind the design live in docs/architecture/discovery-contexts.md.

Who this helps

• Platform users get a clean kubectl api-resources — only the APIs relevant to the URL they're hitting.
• Service teams building on Milo tag their CRDs and immediately feel native alongside Milo's own APIs. No new registration step.
• Documentation and tab-completion stop drowning users in irrelevant resources they can't use.

Scope

This is a discovery hint — it changes what the list endpoints return, not what the server accepts. A caller who already knows a GVR can still talk to it directly. Turning this into a hard boundary would mean pairing the filter with an admission check; that's deliberately out of scope for this change and called out in the doc.

Three existing Milo resources are opted in as the first examples: Organization (Root), Project (Organization), OrganizationMembership (Organization + User). Everything else stays visible everywhere until its owner chooses to tag it.

Follow-up: aggregated apiservers

This PR covers CRDs — Milo's own types and any CRD an external service installs. It does not yet cover the aggregated apiservers Milo already proxies (activity.miloapis.com, quota.miloapis.com, search.miloapis.com, incidents.operations.miloapis.com, identity.miloapis.com). Those are a larger slice of the user-facing surface than CRDs, so coverage is important.

The filter already captures aggregated responses — only the source-of-truth for the mapping is missing. A follow-up PR will add a second registry source that reads an x-milo-parent-contexts OpenAPI extension from the aggregated OpenAPI doc each aggregated service already serves. Each aggregated service will get a small companion PR to emit the extension on its schemas. Sequencing this as a follow-up keeps each change small and reviewable.

Test plan

• Unit tests for parser, registry precedence, and per-context filtering (go test ./pkg/server/discovery/...)
• Chainsaw e2e covering Root / Organization / User + an external CRD installed mid-test (task test:end-to-end -- discovery-context-filter)
• Manual kubectl api-resources against a live dev cluster in all three contexts
• Reviewer verifies annotations on Organization, Project, OrganizationMembership render correctly after task generate

🤖 Generated with Claude Code

[joggrbot]

📝 Documentation Analysis

All docs are up to date! 🎉

---

✅ Latest commit analyzed: 06ba99d | Powered by Joggr

[gianarb]

thanks!!