Skip to main content
Version: main 🚧

Manage Allowed Templates

Allowed templates are the templates that project members are allowed to use when creating resources in a project.

Project and tenant allowlists follow different rules

In a tenant's project, a project member reaches only what both the project and the tenant allow. The two layers write "everything" and "nothing" differently.

LayerFieldTo allow everythingTo allow nothing
ProjectallowedTemplates, a list of namesAdd an entry named "*" for each template kindLeave the field unset or empty
Tenantallow.byLabels, a label selectorSet an empty selectorOmit the selector

An empty tenant selector matches every admin-owned template. An omitted selector grants none by label, but the tenant still reaches any template assigned to it or shared with every tenant. The tenant capability must also be enabled. A disabled capability withholds every template, including ones assigned to the tenant.

A project allowlist can't add inventory the tenant was never granted. See Tenant boundary reference.

Security best practices​

By default, vCluster Platform requires templates for non-admin users to create clusters. This default exists because creating clusters without templates can pose security risks.

Why templates matter for security

When users create clusters without a template, they have full control over the vCluster configuration. Misconfigured settings can allow users to:

  • Access control plane cluster resources they should not have access to through sync settings
  • Sync sensitive resources from the control plane cluster into the cluster
  • Create resources in the host namespace that affect other workloads
  • Deploy arbitrary resources to the host namespace using experimental.deploy.host, which inherits the platform's permissions and can create role bindings or cluster role bindings
  • Access the host namespace through Namespace Objects and Namespace Apps, which deploy resources directly to the control plane cluster

Recommendations​

  1. Keep templates required: The default requireTemplate setting ensures non-admin users can only create clusters from pre-approved templates. Do not disable this setting unless you trust all project members with full vCluster configuration access.

  2. Use hardened templates: Configure templates with restricted sync settings. See security hardening for guidance on creating secure templates.

  3. Review allowed templates carefully: Only add templates to a project that have been reviewed for security implications. Avoid using "All Templates" unless all available templates are appropriately secured.

  4. Limit admin access: Only grant project admin or platform admin roles to users who need the ability to create clusters without templates.

Projects inside a tenant

In a project that belongs to a tenant, every cluster must name an allowed template, whoever creates it. Tenant admins, project admins, and platform admins are all held to it. The requireTemplate waiver doesn't apply in a tenant's project, and a tenant can't turn the waiver on.

Add templates​

Only project admins or global admins can add more templates to a project.

  1. Select the project you'd like to configure using the project selector dropdown. Click Project Config.

  2. Click on Template Options.

  3. In Template type, select Clusters, Namespaces, or Stack templates.

  4. Select Allow only specific templates, click Add allowed template..., and select the template to add. To edit the list directly, use the YAML editor.

  5. Once all project options have been specified, click the .

Allow all templates

Instead of adding every template, select Allow all templates to give the project every template of that type. In YAML, this is an entry named "*" for that kind. Use this option with caution.

Allow StackTemplates​

A StackInstance that references a StackTemplate is rejected unless the project allows that StackTemplate, with template is not allowed in project <project>. The same rule applies to Stacks that a cluster declares under deploy.stacks. There, the cluster reports stack template is not allowed in this project on its StacksSynced condition. Add an entry with kind: StackTemplate, or "*" for every StackTemplate:

Project spec
spec:
allowedTemplates:
- kind: VirtualClusterTemplate
group: storage.loft.sh
name: "*"
- kind: StackTemplate
group: storage.loft.sh
name: "*"

New projects created in the UI, the default project, and each tenant's default project include the StackTemplate "*" entry. A project created through the API, kubectl, or GitOps gets only the entries its manifest lists.

The check arrived in Platform v4.12.2. On the first upgrade to a version with the check, the platform adds a StackTemplate "*" entry to each existing project that has no StackTemplate entry. This runs once, so existing Stacks keep working. It skips projects annotated with loft.sh/skip-update: "true". You can remove the entry afterwards to restrict a project. Under GitOps with self-heal, add the entry to your project manifests, or the GitOps controller reverts it.

requireTemplate doesn't apply to Stack templates. The UI also shows a Default template selector for Stack templates, but Stacks ignore it.

Set a default template​

A default template can be selected for a project, so that the template is automatically selected when creating the resource. The default template is not enforced during resource creation.

  1. Select the project you'd like to configure using the project selector dropdown. Click Project Config.

  2. Click on Template Options.

  3. Select which resource you want to set a default template.

  4. Select the name of the template to set the default template. If you wish to change this manually, you may edit the YAML directly.

  5. Once all project options have been specified, click the .

Advanced: Setting a Namespace Pattern​

When creating a resource, it can be repetitive to specify a spec.clusterRef. namespace in each resource. Namespace patterns provide a template to use when creating namespaces for resources. These can be used to save time or enforce a naming convention.

For example, the namespace pattern {{.Values.loft.project}}-{{.Values.loft.name}} would result in a namespace with name my-project-space-1 being created for the space instance named space-1 for a project named my-project.

  1. Select the project you'd like to configure using the project selector dropdown. Click Project Config.

  2. Click on Template Options.

  3. Expand the Advanced Options section.

  4. Click on the Namespace Pattern input and enter a namespace pattern. If you wish to change this manually, you may edit the YAML directly.

  5. Once all project options have been specified, click the .

Available variables for clusters​

The variables available for templating namespacePattern.virtualCluster are:

  • .Values.loft.user.name: The name of the owner, if the owner is a user
  • .Values.loft.team.name: The name of the owner, if the owner is a team
  • .Values.loft.name: The name of the space or cluster instance
  • .Values.loft.project: The name of the project
  • .Values.loft.space: The name of the space containing the cluster
  • .Values.loft.cluster: The name of the connected cluster the space is scheduled to
  • .Values.loft.virtualClusterName: The name of the cluster
  • .Values.loft.virtualClusterNamespace: The name of the space containing the cluster

Available variables for spaces​

The variables available for templating namespacePattern.space are:

  • .Values.loft.user.name: The name of the owner, if the owner is a user
  • .Values.loft.team.name: The name of the owner, if the owner is a team
  • .Values.loft.name: The name of the space or cluster instance
  • .Values.loft.project: The name of the project
  • .Values.loft.cluster: The name of the connected cluster the space is scheduled to