Scopes: Project & Platform

How Datum Cloud resources are scoped to a Project or shared across the Platform, and what that means for your active context and the —project/—organization flags.

A concept reference for the Scope row you see in every resource page’s Identity table. To put scoping into practice with the CLI, see Contexts & scoping.

Every resource in this reference is either Project-scoped or Platform-scoped. The Identity table at the top of each resource page states which one it is:

Scope	Project or Platform

Scope answers two practical questions: where does this resource live, and which context do I need to be in to create, list, or read it.

The two scopes

Project-scoped

The resource lives inside a single Project. It is created, listed, and read within the context of that Project, and it is isolated from resources in other Projects.

Platform-scoped

The resource is shared across the platform — not owned by any one Project. Platform-scoped resources are often read-mostly and provided by Datum.

Project-scoped resources

Most resources you create are Project-scoped. They belong to exactly one Project, so two Projects can each have their own resource of the same kind and name without conflict. Listing a Project-scoped kind returns only the resources in the Project you are currently working in.

Examples of Project-scoped resources:

• DNSZone — an authoritative DNS zone that lives inside a Project.
• HTTPRoute — routing rules attached to a Gateway within a Project.

A resource’s metadata still carries a namespace field, and Project-scoped resources are addressed within a Project. But the user-facing scoping concept in Datum Cloud is simply Project — you do not manage or reason about the underlying namespace field to use these resources. See Object metadata for how that field is handled.

Platform-scoped resources

Platform-scoped resources are shared across the whole platform rather than being owned by a Project. They tend to be read-mostly and provided by Datum — you reference them from your own Project-scoped resources, but you rarely create or change them yourself. Some Platform-scoped resources (like the organizations and projects that define your account structure) are created by you, just not from within a Project.

Examples of Platform-scoped resources:

• GatewayClass — a class of Gateways available across the platform. A Project-scoped Gateway references a GatewayClass by name.
• Organization and Project — the top-level containers that your Project-scoped resources ultimately live within.

When a Project-scoped resource references another resource by name only (with no Project attached), that referenced resource is usually Platform-scoped — for example a Gateway naming its GatewayClass. Check the referenced resource’s own Identity table to confirm its scope.

How scope maps to your context

The CLI always operates in an active context — an organization and, for most work, a project. Scope determines which part of that context a resource lives in:

Resource scope	Resolved by	What you’re working in
Project	your active project	resources inside one Project
Platform	your active organization / the platform	resources shared across the platform

You set the active context once and let subsequent commands inherit it, or you override it per-command with flags:

• --project <name> — target a specific Project for a Project-scoped resource, regardless of your active context.
• --organization <name> — target a specific organization when resolving Platform-scoped or organization-level resources.

For the full model — how the active context is chosen, cached, and switched — see Contexts & scoping.

If you run a command against a Project-scoped resource without an active Project (and without --project), the command has nothing to scope to and will not resolve. Set a context or pass --project. See Contexts & scoping.

What scope means for creating and listing

Creating. When you apply or create a Project-scoped resource, it is placed in your active Project (or the one named with --project). You do not add a Project field to the manifest — the Project comes from your context. Platform-scoped resources are created without a Project; the ones Datum provides you will typically never create at all.

Listing. datumctl get <kind> lists Project-scoped resources from your active Project only — switch Projects (or pass --project) to see a different Project’s resources. For Platform-scoped kinds, get returns the platform-wide set that your organization can see.

# Project-scoped: lives in, and lists from, one Project
datumctl apply -f dnszone.yaml --project my-project
datumctl get dnszones --project my-project

# Platform-scoped: shared across the platform, no Project needed
datumctl get gatewayclasses

Whether a kind is Project- or Platform-scoped is a property of the resource, not something you choose. Always check the Identity table on the resource’s own page.

Related guides

• Contexts & scoping — the active context model and the --project/--organization flags in depth.
• Reading resources — get and describe across scopes.
• Changing resources — creating and editing resources.
• Safe changes & declarative config — diffing and dry-running before you write.
• Discovering resources & schemas — find which kinds exist and inspect their fields.
• Output formats & scripting — machine-readable output for automation.

The Datum Cloud API is currently alpha (v1alpha1; the Gateway API resources are served at the stable v1). Resources, fields, and scoping may change in backward-incompatible ways between releases.