Create and configure a tenant
This page covers the platform admin workflow. You create a tenant and decide what platform inventory it can consume. You then assign any resources it gets exclusively, configure its hostnames and branding, and hand it to a tenant admin, who takes over from there.
Only a platform admin can do this. A tenant admin can't widen their own boundary.
Before you start​
- Confirm the Multi-Tenancy feature is active in your license. See the overview.
- Decide how you'll select inventory. Label-based grants scale better than naming instances one by one, and templates accept labels only. See what each capability offers before you choose.
Create the tenant​
- UI
- YAML
Click Platform > Tenants.
Click .
Give the tenant a name. The name becomes a prefix on the cluster-scoped resources the tenant owns, so keep it short and recognizable. See the name rules below.
Optionally set a display name and description. The display name is what tenant users see.
Click . You can grant inventory now or come back to it.
In the Invite Tenant Admin dialog, click . Store the link securely until you're ready to hand off the tenant. The dialog shows the link only once.
A tenant with no grants. This is a valid starting point, and the tenant can't reach anything until you add capabilities.
apiVersion: management.loft.sh/v1
kind: Tenant
metadata:
name: acme
spec:
displayName: Acme Corp
description: Production tenant for Acme
Apply it with kubectl apply -f tenant.yaml against the platform API.
Use metadata.generateName instead of metadata.name to have the platform
append a random suffix. One of the two is required. Both are subject to the name
rules below.
Name rules​
A tenant name is a DNS label of 32 characters or fewer, with no dots and no
--. A generateName prefix is limited to 27 characters. The name can't be
changed later, so a rename means creating a new tenant. A name that matches the
NICo org of an existing NICo node provider is refused, because that org is
reserved for platform workloads.
What gets created with it​
Creating a tenant also creates three objects.
| Object | Name | Purpose |
|---|---|---|
| User | <tenant>--admin | The tenant admin |
| Team | <tenant>--admins | Holds the tenant admin's rights inside the boundary |
| Project | <tenant>--default | Somewhere for the tenant admin to start |
To make another tenant user a tenant admin, add them to the team.
Platform leaves any of the three alone if it already exists.
Deleting a tenant doesn't delete its users, teams, projects, or clusters. They stay in place, still labeled for that tenant. A new tenant created with the same name takes them over, including the old admin account and its credentials. Don't reuse a deleted tenant's name for a different customer.
A cluster-scoped resource the tenant owns must be named <tenant>--<name>,
whether the tenant or a platform admin creates it, or it's refused. See resource names.
Grant object access​
Every tenant starts with no grants to platform inventory. For each capability, turn it on and select the instances the tenant may use. A capability that's on without a selector grants nothing.
An empty label selector, byLabels: {}, grants every admin-owned instance of
that kind, including ones you add later. An omitted selector grants none. A
disabled capability withholds everything of that kind, including instances
assigned to the tenant and ones it created. See
selector semantics.
- UI
- YAML
Click Platform > Tenants and click on the tenant's row.
Click Object Access. It has one entry per capability.
For each capability you want to grant, click Selected or All. Selected lists the instances, and the ones you check are granted by name. Click Match by label to grant by label instead, and Select Manually to switch back. Templates offers labels only. For Control Plane Clusters, All is disabled. SSH Keys has a switch instead of a selector, because turning it on lets the tenant create its own keys. A tenant created in the UI starts with SSH Keys turned on.
Optionally, click Object Quotas and set quotas under Node Types to cap how many instances of each type the tenant can hold across its projects. The section appears only after Node Types is set to Selected or All. See the note on node type quotas below.
Click .
Labels under tenant.example.com here are your own. You choose them and apply
them to your inventory. Labels under tenant.vcluster.com, later on this page,
are reserved by the platform.
apiVersion: management.loft.sh/v1
kind: Tenant
metadata:
name: acme
spec:
displayName: Acme Corp
controlPlaneClusters:
enabled: true
allow:
byLabels:
tenant.example.com/pool: shared
nodeTypes:
enabled: true
allow:
byName:
- eu-west.medium
- eu-west.large
quota:
byType:
eu-west.medium: "10"
eu-west.large: "4"
osImages:
enabled: true
allow:
byLabels:
tenant.example.com/tier: standard
custom:
enabled: true
templates:
enabled: true
allow:
byLabels:
tenant.example.com/tier: standard
sshKeys:
enabled: true
allow:
custom:
enabled: true
connectors:
enabled: true
allow:
byLabels:
tenant.example.com/tier: standard
Confirm the grant landed​
Read the controller's resolved boundary report back.
kubectl get tenant acme -o jsonpath='{.status.boundary}' | jq
A capability you granted should show its selectors, and a kind you didn't grant
should show a hidden baseline with nothing singled out. Selector changes don't
wait for this report to update. The derived node provider grant is the exception
and changes when the tenant controller reconciles it.
What each capability offers​
Capabilities don't all support the same selectors, because they don't all mean the same thing. A tenant can't author a control plane cluster, so that capability has no option to let it try.
| Capability | By label | By name | Tenant can author its own | Quota |
|---|---|---|---|---|
| Control plane clusters | Yes | Yes | No | No |
| Node types | Yes | Yes | No | Yes |
| OS images | Yes | Yes | Yes | No |
| SSH keys | No | No | Yes | No |
| Templates | Yes | No | No | No |
| Connectors | Yes | Yes | No | No |
The UI offers both selectors wherever the table does. Switching a capability between Select Manually and Match by label clears the list of the mode you leave, and All clears both.
A tenant with access to the cluster where vCluster Platform runs can escalate its permissions and break tenant isolation. The form warns when you check that cluster, or when a label selector might include it.
The SSH keys capability has no selector for the platform's own keys. Turning it on decides whether the tenant may register keys of its own. A platform admin can still lend a specific key with an exclusive assignment.
A tenant reading a connector sees its configuration but never its credentials. A cluster or OS image that names a connector the tenant can't use is refused when written. If you withdraw a connector later, a cluster that's already using it keeps its database. See Troubleshoot tenants.
nodeTypes.quota.byType caps how many instances of each node type the tenant
can hold, counted across all its projects. It caps on-demand capacity only, so
what counts depends on where an instance lands:
- A Metal3 or NICo node type with the
Assignedmachine allocation policy isn't limited, because it only draws on capacity assigned to the tenant. Metal3 and NICo node types useAssignedunless you set otherwise. - New
OnDemandinstances use only unassigned machines and count toward the quota. - Requests pinned to a specific machine never count.
- A node type from a provider without a machine inventory, such as KubeVirt or Terraform, counts every instance.
How Platform enforces the quota depends on the request. A request that names
the node type directly is refused with a quota exhausted error. A request that
lets Platform choose the node type, such as from a node pool, waits as Pending
with the reason TenantNodeTypeQuotaExceeded until capacity frees up. An
instance keeps counting until its NodeClaim is fully deleted, including while
it's Failed.
A quota doesn't set machines aside for the tenant. To reserve hardware, assign machines to the tenant. To cap a single project, set project quotas. For the full counting rules, see Quotas.
A capability that offers both selectors accepts only one of them. Setting
byName and a non-empty byLabels together is refused. To grant a named set
plus one extra, label the extra one and widen the label selector instead. An
empty byLabels: {} next to byName is accepted, but it grants every
admin-owned instance and makes the name list irrelevant.
A name grant reaches only admin-owned instances, never an instance another tenant owns. A name that doesn't match an instance yet isn't an error. The grant takes effect shortly after an instance with that name is created. Name grants apply after a short reconciliation, unlike label grants, which apply on the next request.
The templates capability covers several kinds at once with a single label selector. One grant reaches cluster templates, apps, stack templates, machine config templates, and Argo CD application templates together. You can't narrow it to one kind. Namespace (space) templates are left out: a tenant sees only the ones it already owns, whatever the grant.
Grant a whole class​
To grant every admin-owned instance of a kind, including ones you add later, use an empty label selector.
osImages:
enabled: true
allow:
byLabels: {}
Assign dedicated resources​
Capabilities select from shared inventory. Some resources instead belong to one tenant outright, and a platform admin assigns them by hand.
Machines and network environments work this way. An assigned resource leaves the platform's available pool and can't be claimed by another tenant. Only a platform admin creates network environments. A tenant uses the ones assigned to it.
Any other resource can be assigned the same way, except projects, clusters, space instances, project secrets, node pools, users, teams, access keys, and config maps. If a capability governs the resource, enable it for the tenant first, or the assignment is refused.
A machine can only go to a tenant that's allowed a node type covering it. Grant the tenant a node type that selects the machine before you assign the machine. A machine that no node type selects can't be assigned to any tenant.
To share one resource with every tenant instead of one, label it
tenant.vcluster.com/all with the value "true". See the
tenant boundary reference.
Read this before assigning a network environment. Once assigned, the assignment can't be added later, changed, or removed. The rest of its spec is frozen too, except the display name, owner, and access. A network environment must name a node provider and be assigned to a tenant or to the platform when it's created.
A machine can be reassigned, but not while it's provisioned. Platform refuses any change to a claimed machine's assignment, including adding or removing one. The UI doesn't let you select a provisioned machine.
- UI
- YAML
Click Bare Metal > Machines.
Select the machines you want to assign.
Click .
Choose the tenant and click .
Assignment is a label on the resource.
metadata:
labels:
tenant.vcluster.com/exclusive-to: acme
Remove the label to return the resource to the platform pool. That works for a machine that isn't provisioned. A network environment's assignment is permanent, so removing the label is refused.
Onboard a tenant to NICo​
Platform onboards a tenant to NICo automatically once you grant it a node type or assign it a network environment that references a NICo node provider. The tenant name becomes its NICo org, so there's nothing to configure.
Platform reports progress as conditions on the tenant.
| Condition | False means |
|---|---|
NICoOnboarded | The NICo org isn't ready yet, or onboarding failed. The reason says which |
NICoNodeProviderFound | A referenced node provider is missing or isn't a NICo provider, or the tenant's grants point at more than one |
NICoSiteCredentialsAvailable | Platform couldn't load the tenant's credentials for the NICo endpoint |
kubectl get tenant acme -o jsonpath='{.status.conditions}' | jq
Allow importing externally deployed clusters​
A cluster deployed outside Platform, for example with vCluster Standalone, Helm, Argo CD, or Terraform, can be imported into a project. For a tenant's users this is off by default, and a platform admin turns it on per tenant.
While it's off, a tenant user who tries to import a cluster is refused. Clusters already imported keep working, and a platform admin can still import a cluster into the tenant's projects.
- UI
- YAML
Click Platform > Tenants and click on the tenant's row.
Click Externally Deployed Clusters, then turn on Allow importing externally deployed clusters (advanced).
Click .
apiVersion: management.loft.sh/v1
kind: Tenant
metadata:
name: acme
spec:
externalClusters:
enabled: true
Configure hostnames and branding​
A tenant carries its own configuration, separate from the platform's.
Hostnames​
A hostname claims a DNS name for a tenant. Platform rejects a hostname that another tenant already claims, and shows a tenant's hostnames in the tenant list. A hostname doesn't change what Platform serves. The sign-in page uses the platform's settings on every hostname, and branding follows the signed-in user.
When a tenant's hostname shows in the tenant list, the invite and password-reset links that a platform admin creates for that tenant's users use the tenant's first hostname. Before you send such a link, make the hostname reach Platform. Point DNS at it, route it to Platform in your ingress or load balancer, and make sure your TLS certificate covers it.
A hostname doesn't select a tenant-specific sign-in method. Depending on the SSO connector and its callback settings, SSO started on a tenant's hostname is refused or finishes on the platform's own hostname. Send users to the platform's sign-in URL unless you have tested SSO on the tenant's hostname.
Hostnames are set by a platform admin only, and can't be delegated. A hostname claims a name the whole platform shares. Completing that claim needs DNS, routing, and a certificate, all outside a tenant admin's reach.
Click Platform > Tenants and click on the tenant's row.
Click Domains, then click .
Enter the hostname, then click .
Point DNS at the platform, route the name to Platform, and confirm your certificate covers the name. Until all three are in place the hostname is stored but never resolves, and the UI still reports the save as successful.
Each hostname can be claimed by one tenant. A hostname already claimed elsewhere is refused, and the error doesn't name the tenant holding it. The check is best effort, so two claims made seconds apart can both be accepted. See Troubleshoot tenants.
UI customization​
Branding changes what a tenant's users see after they sign in. A platform admin sets it in the UI Customization section of the tenant. Tenant admins can't set their own branding.
See Brand a tenant for the steps, which platform settings carry over to tenant users, and how licensing applies.
Hand off to the tenant admin​
The <tenant>--admin user created alongside the tenant is the tenant admin.
If you created the tenant in the UI, send the invite link you copied to whoever
runs the customer's platform. The link lets them set a password and sign in.
If you created the tenant from YAML or didn't copy the original link, generate
a new link for the <tenant>--admin user. See
Reset a user's password.
After signing in, the tenant admin can create further users inside the tenant.
A tenant admin holds full rights inside the boundary. They manage their own users and teams, configure their own projects, and use everything you granted. They can't see the platform's other tenants, and they can't change what you granted them.
A user is bound to a tenant and stays there. A team can only add users from its own tenant, and a platform team can only add platform users. Platform refuses a write that adds a tenant user to a team no tenant owns.
user "acme--bob" belongs to tenant "acme"; an object no tenant owns can only name platform users and teams
A platform team can still name a platform user who hasn't signed in yet.
Verify the boundary​
The quickest check is to look at the platform as the tenant admin does.
Click Platform > Tenants.
Open the tenant's row menu and click .
In the Switch to Tenant dialog, choose the tenant's admin user and click .
Confirm the tenant sees the inventory you granted and nothing else. A banner shows you're impersonating.
Exit impersonation to return to your own view.
Impersonation needs the management admin role or the Impersonator management
role. See Impersonate a user.
A label grant takes effect on the next request, and a name grant shortly after, so refresh an impersonated view you already had open. A stale view shows the old inventory and reads as a failed grant.
Troubleshoot​
If the tenant can't see inventory you granted, if a name or membership write is refused, or if a tenant can't be created, see Troubleshoot tenants.