Skip to content

docs/usage.md says inventory is 'project-scoped'; API types are cluster-scoped — reconcile #37

Description

@ecv

Summary

docs/usage.md describes inventory resources as project-scoped, but every inventory kind is defined cluster-scoped (+kubebuilder:resource:scope=Cluster) and served on the Milo control plane, not a per-project control plane. The doc and the code disagree.

Evidence

docs/usage.md:3-6:

Inventory resources are project-scoped: they are served by the
inventory.miloapis.com API group on a project's control plane, behind project
access control (you need access granted on the project).

But all 12 kinds (api/v1alpha1/*_types.go) are cluster-scoped, with no project owner. M6 (#34) also settles the audience as staff/operators, with activities surfaced platform/org-scoped — not per-project. The new docs/querying-and-activity.md (PR #35) already documents the cluster-scoped, platform-scoped model, which now contradicts usage.md.

Why it matters

  • Misleads operators about where the API lives (Milo control plane vs. a project control plane) and how access is granted.
  • Internally inconsistent docs: usage.md vs. querying-and-activity.md.

Suggested fix

Reconcile docs/usage.md to the cluster-scoped reality:

  • Rewrite the opening "project-scoped" framing to "cluster-scoped on the Milo control plane, infra/operator-facing."
  • Revisit the "Point datumctl at the project control plane" section and any project-access-control wording.
  • Confirm there isn't a genuine project-scoped surface intended (e.g. VirtualMachine.projectRef is the only natural project association, and even then the audience is operators) — if there is, document the split explicitly instead.

Left usage.md untouched in PR #35 (out of that PR's scope); filing here for a focused docs pass.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions