Skip to main content
Version: main 🚧

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​

  1. Click Platform > Tenants.

  2. Click .

  3. 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.

  4. Optionally set a display name and description. The display name is what tenant users see.

  5. Click . You can grant inventory now or come back to it.

  6. 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.

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.

Full name rules →

What gets created with it​

Creating a tenant also creates three objects.

ObjectNamePurpose
User<tenant>--adminThe tenant admin
Team<tenant>--adminsHolds the tenant admin's rights inside the boundary
Project<tenant>--defaultSomewhere 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 leaves its objects behind

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.

Names are prefixed

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 selector isn't an omitted one

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.

  1. Click Platform > Tenants and click on the tenant's row.

  2. Click Object Access. It has one entry per capability.

  3. 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.

  4. 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.

  5. Click .

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.

CapabilityBy labelBy nameTenant can author its ownQuota
Control plane clustersYesYesNoNo
Node typesYesYesNoYes
OS imagesYesYesYesNo
SSH keysNoNoYesNo
TemplatesYesNoNoNo
ConnectorsYesYesNoNo

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.

Don't grant the control plane cluster that runs the platform

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.

Node type quotas cap on-demand usage, they don't reserve machines

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 Assigned machine allocation policy isn't limited, because it only draws on capacity assigned to the tenant. Metal3 and NICo node types use Assigned unless you set otherwise.
  • New OnDemand instances 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.

Network environment assignment is one-way

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.

  1. Click Bare Metal > Machines.

  2. Select the machines you want to assign.

  3. Click .

  4. Choose the tenant and click .

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.

ConditionFalse means
NICoOnboardedThe NICo org isn't ready yet, or onboarding failed. The reason says which
NICoNodeProviderFoundA referenced node provider is missing or isn't a NICo provider, or the tenant's grants point at more than one
NICoSiteCredentialsAvailablePlatform 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.

  1. Click Platform > Tenants and click on the tenant's row.

  2. Click Externally Deployed Clusters, then turn on Allow importing externally deployed clusters (advanced).

  3. Click .

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.

  1. Click Platform > Tenants and click on the tenant's row.

  2. Click Domains, then click .

  3. Enter the hostname, then click .

  4. 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.

Users belong to one tenant

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.

  1. Click Platform > Tenants.

  2. Open the tenant's row menu and click .

  3. In the Switch to Tenant dialog, choose the tenant's admin user and click .

  4. Confirm the tenant sees the inventory you granted and nothing else. A banner shows you're impersonating.

  5. 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.

Next steps​