Skip to main content
Version: v5.0 Stable

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, or shared, meaning the tenant sees all of them.

Those two facts come from one of three places, in order.

  1. 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.
  2. A shipped default covers it. The table below applies.
  3. 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
FieldMeaning
resourceThe Platform resource name, lowercase plural
enabledThe governing capability's switch. Absent where no capability governs the resource. false means the tenant reaches nothing of this resource
ownWhether the tenant can author its own instances
baselinehidden or shared, for instances no selector matches
byLabelsThe label selector the capability grants with
byNameInstances granted by exact name
derivedInstances 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.

ResourceCapabilityTenant can author its own
clusterscontrolPlaneClustersNo
nodetypesnodeTypesNo
osimagesosImagesYes, with allow.custom.enabled: true
sshkeyssshKeysYes, with allow.custom.enabled: true
virtualclustertemplatestemplatesNo
appstemplatesNo
stacktemplatestemplatesNo
machineconfigtemplatestemplatesNo
argocdapplicationtemplatestemplatesNo
connectorsconnectorsNo

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.

ResourceWhat it is
projectsProjects
virtualclusterinstancesClusters
projectsecretsProject secrets
nodepoolsNode pools
nodeclaimsInstances (NodeClaim)
argocdapplicationsArgo CD applications
appinstancesApp instances
stackinstancesStack instances
virtualclusterschemasCluster schemas
machinesMachine inventory mirrors (physical servers)
nodeprofilesNode profiles
networkpeersNetwork peers
usersUsers
teamsTeams
oidcclientsOIDC clients
databaseconnectorsDatabase connectors
accesskeysAccess keys
configmapsConfig 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​

ResourceWhat it is
networkenvironmentsNetwork 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​

ResourceWhat it is
nodeprovidersNode 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​

ResourceWhat it isTenant can author its own
clusterroletemplatesCluster role templatesNo
clusterrolesKubernetes cluster rolesNo
rolesKubernetes rolesNo

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​

ResourceWhat it isTenant can author its own
tenantsTenantsNo
clusteraccessesCluster accessesNo

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.

RuleReason
Lowercase alphanumeric and hyphensDerived names have to be valid DNS labels too
Starts and ends alphanumericSame reason. A metadata.generateName prefix is the exception and can end in a hyphen
No dotsA project's namespace is derived from the name
No -- sequence-- separates the tenant name from the resource name
metadata.name is 32 characters or fewerEverything the tenant owns is named after it, and <tenant>--default still has to fit the project name budget
metadata.generateName is 27 characters or fewerKubernetes 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​

ObjectName
Tenant admin user<tenant>--admin
Tenant admin team<tenant>--admins
Default project<tenant>--default

Selector semantics​

WrittenMeans
Capability absentWithheld. 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: falseSame as absent
enabled: true, no allowEnabled, 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 nullNo 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.