Skip to main content
The path /org/my-org/gvc/my-gvc/workload/my-app in an API call, the --org and --gvc flags on a CLI command, and the kind and name in a manifest are three views of the same addressing scheme. The scheme mirrors the scoping: a GVC is scoped to the 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

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. 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, 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 and Pulumi providers, the Kubernetes operator, and AI agents issue the same requests, so nothing is reachable from one interface and hidden from another, and every change lands in the same audit trail.
  • 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

Reference overview

Every resource kind, grouped by what it does.

Deploy with cpln apply

Declare resources as YAML and apply them from a repository.

Query spec

Select items by tag and property instead of naming each one.

CLI profiles

Set the org and GVC your commands resolve against.