Templates

Virtual cluster templates are, as the name implies, templates that you can create which can then be applied when creating a virtual cluster. These templates can be used to configure any virtual cluster settings that you would configure on an individual virtual cluster.

Virtual cluster templates are used for creating a standard developer environment for a given team or organization or to template out pre-built environments to be used in continuous integration and testing.

As regular project users can only deploy new virtual clusters via template, templates provide a mechanism for vCluster.Pro administrators to expose acceptable virtual cluster configurations to end users.

Templates can include settings such as:

• Isolation relevant objects in the host namespace, such as resource quotas, limit ranges and network policies.
• Helm values for configuring the virtual cluster itself
• Kubernetes objects (including CRDs!). This could include development tooling, pre-populated databases with test data, or any other useful resources.
• Custom defined Apps

Create Virtual Cluster Template

Virtual cluster templates can be created directly in the vCluster.Pro UI.

1. In the vCluster.Pro UI, select the Templates field on the left-most menu bar.
2. From the Templates sub-menu, select the Virtual Clusters option.
3. Click button.
4. In the drawer that appears from the right, give your virtual cluster template a name by replacing the 'my-template' placeholder name, or by updating the manifest YAML 'metadata.name' field.
5. [Optional] Update the template with any additional desired configuration options.
   1. The Definition tab contains settings relating to the virtual cluster deployment itself, here you can provide helm values to be used when deploying the virtual cluster, select the virtual cluster distribution (ex: k3s (default), k0s, k8s), as well as configurations for sleep mode and ingress access.
   2. Objects is where you can define Kubernetes manifests that should be created in the virtual cluster.
   3. Apps allows you to select any pre-defined 'applications' (ex: Cert Manager) that should be installed into the virtual cluster.
   4. Parameters provides a mechanism for exposing values that users should be able to modify when deploying a virtual cluster from this template.
   5. Space settings allow for configuration of labels and annotations on the space that the virtual cluster will be created in, you can also define objects and Apps that should be deployed into this space.
   6. Permissions are additional access rules that can be defined for the virtual cluster instance.
   7. Finally, Template Permissions are the permissions that are applied to the template itself -- that is, who has permission to view/edit this template.
6. Click on the button at the very bottom.

Using Templates (UI & CLI)

Once you have created a virtual cluster template you can then refer to that template when creating a new virtual cluster. All template configurations will be automatically applied to the newly created virtual cluster. Virtual clusters referring to templates can be created in the UI or via the vCluster.Pro CLI.

UI

1. Select the Projects field on the left menu bar.
2. From the project drop-down menu, select the project you'd like to create the virtual cluster in.
3. Click the Virtual Clusters option on the project pane.
4. Click the button on the right side of the page.
5. In the pop-up box, select your template from the template drop down menu.
6. [Optional] select the cluster in which to create the virtual cluster.
7. Click the to continue.
8. In the drawer that appears from the right, give your virtual cluster a name by replacing the my-vcluster placeholder name, or by updating the manifest YAML metadata.name field.
9. Click the button.

10. Retrieve a kube-context for a virtual cluster using vCluster.Pro CLI:

    vcluster connect [vcluster-name] --project [project-name]

CLI

When creating a virtual cluster from the vCluster.Pro CLI, you will need to provide the name of the project in which to deploy the virtual cluster, and the name of template to use:

vcluster pro create [vcluster-name] --project [project-name] --template [template-name]

Template

If you omit specifying a template, vCluster.Pro will automatically select one for you (if there is a default template in the project specified) or prompt you to select a template.

Kube-Context

Running vcluster pro create will automatically add a kube-context to your kube-config file, so you can immediately run kubectl commands right after creating a virtual cluster.

Versioning

Virtual cluster templates can be versioned. Versioning a virtual cluster template allows you to make changes over time to a template while retaining the current version/iteration. Virtual clusters that are deployed with templates that have updated versions will show up with a warning indicating that a newer template version is available.

Creating A New Virtual Cluster Template Version

You can add new versions to your virtual cluster templates via the vCluster.Pro UI.

1. Select the Templates field on the left menu bar.
2. Click the Virtual Clusters option on the templates pane.
3. Find the virtual cluster template you would like to add a new version to in the list of virtual cluster templates. Click the small drop down button next to the name of your desired virtual cluster template. From the drop down menu, click the Add A New Version button.
4. In the pop up box, enter the new version string for your App. Once done, click the.
5. In the drawer that appears from the right, make any modifications desired for your new virtual cluster template version.
6. Click the button.

Updating a Virtual Cluster's Template Version

You can change the virtual cluster template or virtual cluster template version in the vCluster.Pro UI.

1. Select the Projects field on the left menu bar.
2. From the project drop-down menu, select the project containing the virtual cluster you'd like to upgrade.
3. Click the Virtual Clusters option on the project pane.
4. Click the dropdown arrow next to the name of the virtual cluster you'd like to modify.
5. In the dropdown menu, select Change Template.
6. In the pop-up window, select the name of the template from the drop down menu -- the currently applied template will already be selected, so if you are just changing the template version you don't need to do anything for this step!
7. If the template you are selecting has multiple versions, you will see an additional version dropdown menu next to the template selector dropdown, select your desired template version from this menu.
8. Click the button.

Parameters

Parameters are a very powerful component of virtual cluster templates. These parameters allow for giving users that may consume your virtual cluster template a bit of flexibility with configuration options for certain applications, while still maintaining control over the possible values the users can select.

When deploying a virtual cluster referring to a template with parameters configured, vCluster.Pro will prompt the user for their selection for the given parameters. For example, with a parameters configuration as shown below, the user will get a dialog box where they can select 'one' or 'two' as the value for the mylabelvalue variable.

- variable: mylabelvalue
  label: StatefulSet Label
  description: Please select the value for the vCluster statefulset "my-label" key
  options:
    - one
    - two
  section: Labels

The final value of this variable can then be used throughout the template. For example, this value can be used within the helm values of the vCluster chart. In the example below, this value is being set as a label on the vCluster statefulset.

labels:
  my-label: "{{ .Values.mylabelvalue }}"

Apps & Parameters

Check out the Apps section of the docs, especially the Parameters section for more details on Parameters generally, and in relation to Apps