> ## Documentation Index
> Fetch the complete documentation index at: https://controlplanecorporation-majid-docs-content-expansion.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource Model

> Every object is an item of a kind, addressed by its kind and a name that never changes, scoped to its org or GVC, and reached through one API that the Console, the CLI, Terraform, Pulumi, and every AI agent share.

The path `/org/my-org/gvc/my-gvc/workload/my-app` in an [API](/api-reference/api) call, the `--org` and `--gvc` flags on a [CLI](/cli-reference/overview) command, and the `kind` and `name` in a [manifest](/guides/cpln-apply) are three views of the same addressing scheme. The scheme mirrors the scoping: a [GVC](/concepts/gvc) is scoped to the [org](/concepts/org), and everything created inside a GVC is scoped to that GVC. Learn it once and every interface reads the same way.

## How It Fits

| Scope | Kinds                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Example link                             |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| Org   | Principals ([users](/reference/user), [groups](/reference/group), [service accounts](/reference/serviceaccount)), governance ([policies](/concepts/access-control), [quotas](/concepts/quota)), infrastructure ([cloud accounts](/reference/cloudaccount), [agents](/reference/agent), [locations](/concepts/location)), assets ([secrets](/reference/secret), [images](/reference/image), [domains](/reference/domain)), and [GVCs](/concepts/gvc) themselves | `/org/my-org/secret/my-secret`           |
| GVC   | [Workloads](/concepts/workload), [identities](/concepts/identity), and [volume sets](/reference/volumeset)                                                                                                                                                                                                                                                                                                                                                     | `/org/my-org/gvc/my-gvc/workload/my-app` |

<img src="https://mintcdn.com/controlplanecorporation-majid-docs-content-expansion/rUryc3z9dDsnWr_V/images/concepts/resource-link.svg?fit=max&auto=format&n=rUryc3z9dDsnWr_V&q=85&s=885afdd896d04598d190a6f329bc34df" alt="Two link shapes. A GVC-scoped item, read left to right: the org /org/my-org, the GVC /gvc/my-gvc, then the kind and name /workload/my-app. Everything you create belongs to one org. The GVC part is only for workloads, identities, and volume sets. The kind, then a name that never changes. An org-scoped item has two parts: the org /org/my-org, then the kind and name /secret/my-secret. Three parts for a GVC-scoped item, two for an org-scoped one." style={{maxWidth:'720px',width:'100%',margin:'1.75rem auto',display:'block'}} width="720" height="344" data-path="images/concepts/resource-link.svg" />

Workloads, identities, and volume sets are the only GVC-scoped kinds. Everything else belongs to the org and is shared by every GVC in it.

## Key Behaviors

* **A kind is a resource type; an item is a single resource of that kind.** `workload` is a kind, `my-app` is an item. Every item carries the same base fields whatever its kind: you set `name`, `kind`, `description`, and `tags`; the server assigns `id`, `version`, `created`, and `lastModified`.
* **Context is an org and, when it matters, a GVC.** The CLI holds both in a [profile](/cli-reference/get-started/profiles), and any single command overrides them with `--org` and `--gvc`; the Console's context is the org and GVC you have open.
* **A relative link starts with `//`, and your context fills in the rest.** In org `my-org`, `//secret/my-secret` resolves to `/org/my-org/secret/my-secret`. With GVC `my-gvc` set, `//workload/my-app` resolves to `/org/my-org/gvc/my-gvc/workload/my-app`, and a link can name a different GVC outright: `//gvc/other-gvc/workload/my-app`.
* **What you write relative, Control Plane stores full.** A relative link is expanded when the item is saved, so the same manifest applied in two orgs produces two items whose stored links differ. The full form is called the self link: every item returns its own with every read, and a stored reference holds the self link of the item it points at.
* **One API is underneath every interface.** The Console, the CLI, the [Terraform](/iac/terraform) and [Pulumi](/iac/pulumi) providers, the [Kubernetes operator](/core/kubernetes-operator), and [AI agents](/ai/overview) issue the same requests, so nothing is reachable from one interface and hidden from another, and every change lands in the same [audit trail](/core/audittrail).
* **Manifests address items by kind and name.** `cpln apply` accepts YAML or JSON declaring `kind` and `name`, creating the item when it is absent and updating it when it is not. A GVC-scoped manifest can name its target GVC in a top-level `gvc` property, which stands in for `--gvc` and the profile.

## Gotchas

* **A name cannot be changed.** The name is the address, so applying a manifest with a new name creates a second item instead of renaming the first. Renaming means creating the new item, repointing every link, and deleting the old one.
* **Names are lowercase, and up to 64 characters.** Start with a letter, continue with letters, digits, and hyphens, and end with a letter or a digit.
* **A relative link is only as portable as the context around it.** The same `//workload/my-app` resolves differently in two GVCs, which is the point when applying a manifest per environment and a hazard when reading one out of context.
* **A GVC-scoped relative link fails without a GVC in context.** From an org-level context, `//workload/my-app` is rejected with `Cannot expand //workload/my-app to a gvc-local link`; write `//gvc/my-gvc/workload/my-app` or set the GVC.
* **Names are unique per kind and scope, not globally.** Two GVCs can each hold a workload called `my-app`, which is why endpoints and internal DNS names include the GVC.

## Learn More

<CardGroup cols={2}>
  <Card title="Reference overview" icon="book-open" href="/reference/overview">
    Every resource kind, grouped by what it does.
  </Card>

  <Card title="Deploy with cpln apply" icon="file-code" href="/guides/cpln-apply">
    Declare resources as YAML and apply them from a repository.
  </Card>

  <Card title="Query spec" icon="filter" href="/core/query">
    Select items by tag and property instead of naming each one.
  </Card>

  <Card title="CLI profiles" icon="terminal" href="/cli-reference/get-started/profiles">
    Set the org and GVC your commands resolve against.
  </Card>
</CardGroup>
