Tenant boundary reference
This page is a lookup table. It covers what a tenant can see and author for each Platform resource, and the labels and naming rules behind that.
For the workflow, see Create and configure a tenant. For symptoms and error messages, see Troubleshoot tenants.
How a resource gets its answer​
Every Platform resource resolves to two facts for a given tenant.
- Can the tenant author its own instances? This gates creating, not reading. A tenant sees what it owns even where it can't add to it, unless a disabled capability withholds the whole resource.
- What happens to the platform's own instances? Either
hidden, meaning the tenant sees only what a grant singles out, orshared, meaning the tenant sees all of them.
Those two facts come from one of three places, in order.
- A capability governs the resource. The tenant's capability decides. An absent or disabled capability withholds the resource outright. The tenant sees none of the platform's instances, none lent to it, and none of its own.
- A shipped default covers it. The table below applies.
- Neither. The resource withholds the platform's instances and lets the tenant keep its own. A resource reaches this case by being new and not yet considered, so the symptom is something missing rather than something disclosed.
Read the resolved boundary​
Platform recomputes the boundary and writes it to the tenant's status, one entry per resource.
kubectl get tenant acme -o jsonpath='{.status.boundary}' | jq
| Field | Meaning |
|---|---|
resource | The Platform resource name, lowercase plural |
enabled | The governing capability's switch. Absent where no capability governs the resource. false means the tenant reaches nothing of this resource |
own | Whether the tenant can author its own instances |
baseline | hidden or shared, for instances no selector matches |
byLabels | The label selector the capability grants with |
byName | Instances granted by exact name |
derived | Instances reached by following a reference from something already granted |
status.hostnames sits alongside status.boundary and lists the DNS names the
tenant claims. The tenant controller projects it from the tenant's
configuration. Don't edit it directly. The controller overwrites manual changes
during its next reconciliation.
The status is mostly a report. Platform works the spec-derived rules out again on every request, so label selector changes don't wait for the report to update. A name grant is applied by a controller, so it takes effect after a short reconciliation.
derived is the exception. Granting a node type also makes its node provider
reachable, since the grant would otherwise be unusable. The tenant controller
resolves that relationship into derived, and the request path reads those
names back from status. Don't edit this field. The controller overwrites manual
changes during its next reconciliation.
Capability-governed resources​
These deny by default. Nothing is visible until the matching capability is enabled. Once it's on, the tenant sees the platform's instances a selector matches, plus any assigned to it or shared with every tenant.
| Resource | Capability | Tenant can author its own |
|---|---|---|
clusters | controlPlaneClusters | No |
nodetypes | nodeTypes | No |
osimages | osImages | Yes, with allow.custom.enabled: true |
sshkeys | sshKeys | Yes, with allow.custom.enabled: true |
virtualclustertemplates | templates | No |
apps | templates | No |
stacktemplates | templates | No |
machineconfigtemplates | templates | No |
argocdapplicationtemplates | templates | No |
connectors | connectors | No |
A capability that's absent or disabled withholds the resource outright. The tenant can't read the platform's instances, instances lent to it, or instances it owns, and it can't create new ones. Instances it created before the capability was switched off stay in place, but the tenant can't see them until the capability is enabled again.
A tenant reading a connector never sees its credentials. Platform redacts them for any caller who can't update the connector, and a tenant can't update one it doesn't own. For some connector types, such as Argo CD and observability, the tenant sees only the name and type.
Shipped defaults​
These resources have no capability. The table is their whole answer.
The Tenant keeps its own, the platform's stay hidden​
This is the common case. A tenant sees the instances it created and none of the platform's.
| Resource | What it is |
|---|---|
projects | Projects |
virtualclusterinstances | Clusters |
projectsecrets | Project secrets |
nodepools | Node pools |
nodeclaims | Instances (NodeClaim) |
argocdapplications | Argo CD applications |
appinstances | App instances |
stackinstances | Stack instances |
virtualclusterschemas | Cluster schemas |
machines | Machine inventory mirrors (physical servers) |
nodeprofiles | Node profiles |
networkpeers | Network peers |
users | Users |
teams | Teams |
oidcclients | OIDC clients |
databaseconnectors | Database connectors |
accesskeys | Access keys |
configmaps | Config maps |
machines and nodeprofiles are resources a platform admin lends by hand. No
capability grants them, so a tenant reaches one of the platform's only through
an exclusive assignment or the share-with-every-tenant label. No one creates a
machine through the API, a platform admin included. The inventory sync creates
them, and only their labels and annotations can be edited.
A machine can only be assigned to a tenant that's allowed a node type covering
it. At least one node type of the machine's provider must select the machine,
and the tenant's nodeTypes capability must allow that node type. Otherwise the
assignment is refused. A machine that no node type selects can't be assigned to
any tenant. Providers that keep no machine inventory aren't checked.
users and teams are the tenant's own identities. A tenant never sees the
platform's users or teams, and a platform team can't be lent to a tenant.
Projects, clusters, project secrets, node pools, users, teams, access keys, and config maps can't be assigned to a tenant. See the exclusive-to label.
Namespaces (space instances) are turned off for tenants. No one can create,
import, or migrate a namespace into a tenant project, a platform admin included.
Each attempt is refused with tenant "acme" may not use this endpoint.
On a cluster in a tenant project, the tenant can't change the inline
spec.template, spec.external, or the loft.sh/skip-helm-deploy annotation.
Those decide what Platform deploys, so only a platform admin can change them.
Every cluster created in a tenant project must name a template the project
allows. This holds for everyone, including tenant admins, project admins, and
platform admins. A request without a template, or with an inline
spec.template, is refused with must reference a template the project allows, and may not supply an inline spec.template. The project's requireTemplate
waiver doesn't apply in a tenant project. A tenant can't turn the waiver on
either. If a platform admin already set it, the tenant's other edits to the
project still go through.
A tenant can't change its project's namespace pattern, which decides the control plane namespace each cluster lands in. Only a platform admin can change it.
Importing a cluster deployed outside Platform into a tenant project is off by default. A platform admin turns it on per tenant. The setting only limits the tenant's own users. While it's off, clusters already imported keep working, and a platform admin can still import into the tenant's projects. See Allow importing externally deployed clusters.
oidcclients and databaseconnectors are sensitive, which is
a reason to hide the platform's instances rather than a reason a tenant may not
hold its own.
Lent by a platform admin, never authored​
| Resource | What it is |
|---|---|
networkenvironments | Network environments |
A tenant can't own a network environment, so it can't create one, and a platform
admin can't create one on a tenant's behalf. Both writes are refused with
may not own instances of this resource. A platform admin creates the network
environment and assigns it to the tenant with the exclusive-to label. The
tenant reads and references it but can't edit it.
Reached through node types, never authored​
| Resource | What it is |
|---|---|
nodeproviders | Node providers |
A node provider acts with the platform's authority, so a tenant can't own one.
A tenant's create is refused with may not own instances of this resource, and
so is a platform admin's create for a tenant. A platform admin creates every
node provider.
A tenant reads a node provider only through the node types its nodeTypes
capability grants. Each granted node type makes its node provider readable, as
described under derived in Read the resolved boundary.
A tenant whose role allows updating node providers is still refused with
may not write an instance it does not own.
Shared with every tenant​
| Resource | What it is | Tenant can author its own |
|---|---|---|
clusterroletemplates | Cluster role templates | No |
clusterroles | Kubernetes cluster roles | No |
roles | Kubernetes roles | No |
A tenant that creates users has to assign them roles, and Platform already ships the roles worth assigning. Authoring stays denied, because writing a cluster role template is writing RBAC.
Every tenant can read every cluster role and role that no tenant owns or holds, including
built-in ones such as cluster-admin. A role grants nothing without a binding,
so reading one gives the tenant no access. A binding that names a role another
tenant owns grants nothing.
Hidden by default​
| Resource | What it is | Tenant can author its own |
|---|---|---|
tenants | Tenants | No |
clusteraccesses | Cluster accesses | No |
The ownership labels below can make a cluster access reachable. They don't
open up tenants. Platform refuses the tenant.vcluster.com/all label on a
Tenant.
Managing tenants belongs to a platform admin session. Cluster accesses stay with the platform admin too, because a cluster access becomes RBAC inside the control plane cluster it names.
A cluster access is also the only way into a cluster's proxy. Seeing a granted
cluster doesn't let a tenant user reach into it. The platform admin must assign
the cluster itself to the tenant with the tenant.vcluster.com/exclusive-to label
and create a cluster access that's assigned to the tenant or shared with every
tenant using the ownership labels below. See
Cluster access and tenants.
Ownership labels​
Three labels record a tenant's relationship to a resource. They answer different questions, and no resource can carry more than one of them. Platform refuses a write that combines them.
tenant.vcluster.com/owner​
The resource belongs to this tenant, and it counts against that tenant. Platform applies the label when a tenant creates a resource. A platform admin sets it when creating a resource for the tenant. A Kubernetes identity, such as a GitOps service account, can't set it on a create. Platform keeps the label on update and refuses any change of tenant. A tenant can neither see nor set it. Platform admins and Kubernetes identities can repeat the stored owner label unchanged on updates and patches.
A resource without the label belongs to the platform. That includes everything created before Platform v5.0. Ownership is fixed at creation, so to give a platform-owned resource to a tenant, recreate it under the tenant. To set the label from Git, see Manage tenant resources with GitOps.
tenant.vcluster.com/exclusive-to​
A platform admin assigned this resource to one tenant. Nothing derives it, because no field in the Tenant spec expresses exclusivity. A platform admin applies and removes it by hand.
metadata:
labels:
tenant.vcluster.com/exclusive-to: acme
The value is the tenant name, and an empty value is refused. To leave a resource
with the platform, remove the label rather than emptying it. The same holds for
tenant.vcluster.com/owner label.
tenant.vcluster.com/exclusive-to must name a tenant; the platform uses whatever no tenant holds, so remove the label rather than setting it to an empty value
Removing the label returns the resource to the pool, with two exceptions. A network environment's assignment is set at creation and can't be added, changed, or removed afterward. A machine's assignment can't change while a node claim holds the machine.
The holding tenant reads and references the resource. Every write, including deletion, stays with the platform admin.
Any resource can carry the label except projects, clusters, space instances, project secrets, node pools, users, teams, access keys, and config maps. Platform refuses it on these kinds.
<resource> cannot be assigned to a tenant with tenant.vcluster.com/exclusive-to
Resources in a project take their tenant from the project, so a loan can't say who owns them. Assigning a user or team would hand over authority rather than lend capacity. Lending an access key or config map would hand over the token or data itself. To lend the use of a credential, use a connector.
If a capability governs the resource, the tenant must have that capability enabled before you assign to it. Otherwise the assignment is refused, because the tenant would never be served it.
tenant "acme" has nodeTypes turned off. Turn it on for the tenant first
The capability field name, such as controlPlaneClusters, nodeTypes,
osImages, sshKeys, templates, or connectors, fills the slot.
tenant.vcluster.com/all​
A platform admin shared this resource with every tenant. Only the value "true"
shares, so any other value withholds.
metadata:
labels:
tenant.vcluster.com/all: "true"
Every tenant can read and reference the resource, and none can write to it. The
label can't go on tenants, or on any kind that refuses the exclusive-to label. It also can't be combined with the
tenant.vcluster.com/owner label or the tenant.vcluster.com/exclusive-to label.
A disabled capability still wins. A tenant with the governing capability switched off doesn't see a shared resource of that kind.
Access rules​
A resource's spec.access rules name the users and teams that may act on it.
The tenant boundary changes what a wildcard in those rules means, and which
users and teams a rule can name.
Wildcards match the resource's own scope​
users: ["*"] or teams: ["*"] in an access rule matches every identity in the
resource's own scope, not every identity on the platform.
- On a resource no tenant owns, it matches the platform's users and team access keys.
- On a resource a tenant owns, it matches that tenant's users and team access keys.
A tenant can see a platform-owned resource through a grant, or through the
tenant.vcluster.com/exclusive-to or tenant.vcluster.com/all label. Such a
tenant can still read the resource through its wildcard rule. The wildcard
grants the tenant nothing beyond reading. On a platform without
tenants, every identity and resource belongs to the platform, so a wildcard
matches what it always did.
A wildcard member of a project follows the same rule. See Project membership.
A tenant names only users and teams it can see​
When a tenant identity adds a user or team reference, it can name only
identities in its own tenant. This applies to new references in spec.access,
changes to spec.owner, and additions to a team's spec.users. A reference to
another tenant's user or team, or one that doesn't exist yet, gets a 403 with
this reason:
not a user or team this tenant can see
The response is the same for a hidden name and a missing one, so a tenant can't use it to discover another tenant's identities.
Platform admins aren't limited to what a tenant can see, but a resource a
tenant owns still names only that tenant's users and teams. A platform admin's
write that names another tenant's user or team gets a 422 with a message that
contains does not belong to tenant "<tenant>", which owns this object. A
platform admin can name a user or team that doesn't exist yet only if its name
starts with the tenant's prefix, such as acme--.
If GitOps authenticates as a tenant identity, apply users and teams before resources that name them. A sync that adds a reference before the identity exists is refused until that identity exists.
Name rules​
Tenant names​
A tenant name must be a valid DNS label. The platform checks it when it accepts the tenant, whether you use the UI or apply YAML.
| Rule | Reason |
|---|---|
| Lowercase alphanumeric and hyphens | Derived names have to be valid DNS labels too |
| Starts and ends alphanumeric | Same reason. A metadata.generateName prefix is the exception and can end in a hyphen |
| No dots | A project's namespace is derived from the name |
No -- sequence | -- separates the tenant name from the resource name |
metadata.name is 32 characters or fewer | Everything the tenant owns is named after it, and <tenant>--default still has to fit the project name budget |
metadata.generateName is 27 characters or fewer | Kubernetes appends a five-character suffix, and the final name must fit the 32-character limit |
This is stricter than Platform's other resources. Users and teams permit dots. Tenants don't, because a tenant name has to survive being embedded in every name derived from it.
A tenant can be created with metadata.generateName instead of
metadata.name, and one of the two is required. The prefix can end in a hyphen,
which Kubernetes places immediately before the generated characters.
The name is immutable after creation, so a rename means creating a new tenant. Everything the tenant owns is derived from it, so treat the name as permanent when you pick it.
Resource names​
A tenant-owned cluster-scoped resource must be named <tenant>--<name>, whoever
creates it. For a tenant called acme, an SSH key called build is named
acme--build.
This applies to every resource the tenant owns, whoever creates it. A platform admin who creates a tenant-owned user, team, or project is held to the same prefix. The rule doesn't apply to resources a platform admin grants or assigns, because the platform still owns those. Namespace-scoped resources are unaffected, because their names are already scoped by the namespace.
The prefix is reserved in the other direction too. A cluster-scoped name that
starts with <tenant>-- must belong to that tenant, even if the tenant doesn't
exist yet. A platform admin can't create a platform-owned or lent resource named
acme--<name>. Platform checks this on create, and only while the Multi-Tenancy
license feature is active. Without it, no tenant can claim a prefix, so names
keep the freedom they had before tenants.
names starting with "acme--" belong to tenant "acme": the object must be owned by it
Omitting the prefix produces a validation error naming the prefix required.
SSHKey.management.loft.sh "build" is invalid: metadata.name: Invalid value:
"build": must start with "acme--": this kind is cluster-scoped, so its name is
shared with every tenant on the platform
Names created with a Tenant​
| Object | Name |
|---|---|
| Tenant admin user | <tenant>--admin |
| Tenant admin team | <tenant>--admins |
| Default project | <tenant>--default |
Selector semantics​
| Written | Means |
|---|---|
| Capability absent | Withheld. The tenant sees none of the platform's instances, none lent to it, and none of its own, and can't author new ones |
enabled: false | Same as absent |
enabled: true, no allow | Enabled, no admin-owned instance selected. The tenant still sees instances it owns, instances assigned to it, and instances shared with every tenant |
allow.byLabels: {} | Every admin-owned instance of that resource, except ones assigned to another tenant |
allow.byLabels absent or null | No admin-owned instances |
allow.byName: [a, b] | Exactly those admin-owned instances. A name that doesn't exist yet takes effect shortly after the instance is created |
Label selectors match all specified pairs. With a non-empty selector, an instance has to carry every pair. An empty selector matches every admin-owned instance, including those without labels. An instance assigned to another tenant is never matched.
controlPlaneClusters, nodeTypes, osImages, and connectors offer both
byName and byLabels, and accept only one of them at a time. Setting byName
with a non-empty byLabels is refused. To grant a named set plus an extra, label
the extra one and widen the label selector. An empty byLabels: {} alongside
byName is accepted and grants every admin-owned instance.