Skip to content

Getting Started with vCluster

Overview

This self-paced guide helps you explore the platform's capabilities for lifecycle management of vClusters using system templates from the template catalog. vClusters are virtual Kubernetes clusters that allow you to create isolated, resource-efficient environments within a larger host Kubernetes cluster.

Prerequisites

Before proceeding, ensure the following:

Pre-Requisites

  • Host Cluster: Ensure that a Kubernetes host cluster is available and ready for vCluster deployment
  • Rafay Configuration: At template launch, supply the following configuration values
    • API Key
    • REST Endpoint
  • Agent Configuration: A configured agent must be available in the project where the template will be used, and it should be in a healthy state. Follow these instructions to deploy a new agent. Existing agents within the project can be reused if available

Part 1: Select and Share the vCluster System Template

This section guides you through selecting and sharing the vCluster system template with a central project where the Org admin can customize it before sharing it with other projects.

Step 1: Create a Project

To begin, create a logically isolated “operating environment” (sub-tenant):

  • Navigate to Home > Your Projects.
  • Click New Project and name it vcluster-project.

Create Project

Step 2: Select and Share the vCluster System Template
  • As an Org Admin, go to Settings > Template Catalog.

Catelog

  • Select the Multi-tenancy category and choose the Multi-tenancy on K8s.
  • Click Get Started.
  • Provide the following details:
  • A unique name for the shared template.
  • A version name (e.g., 1.0).
  • Select the project to share the template with (e.g., vcluster-project).

Create Project

  • After sharing, the platform redirects you to the selected project (vcluster-project).

Create Project

  • Go to Agents and configure the required Agent to drive the workflow. Select the Agent from the dropdown list. If no Agents are shown, the Agent may need to be set up (refer to the prerequisites).

Create Project

Configuration Customization
  • Customize and templatize all vCluster configurations using input variables, including:
  • Namespace settings: Labels, annotations, quotas, container limits
  • vCluster parameters: Name, version, store size, runtime (Kata), network policy
  • Blueprint management: Blueprint and version
  • Access control: Username, project, kubeconfig options

  • Host cluster setup: Host project, host cluster name

  • Restrict user edits for specific variables by:

  • Setting overrides to Not Allowed for certain variables
  • Defining default values that cannot be edited at the time of launch

Create Project

  • Provide authentication details for creating a vCluster by setting the API key. The Org Admin can either set the API key by editing the Inline config context (e.g., rafay-auth-config) or take it as input while launching the template. To set the key, edit the Inline configuration context as shown below

Config Context

CC Configuration

This ensures consistency and prevents unauthorized changes by end users.

  • Save the template as a Draft to allow ongoing edits until the configuration is finalized. Once all changes are complete, set it as an Active Version to freeze the version. Learn more about version management.

Save Version

Part 2: Launch the Template to Create an vCluster

You can launch the template within the same project or share it with other projects for end-user access.

  • Go to the Environments section within the vcluster-project project or the shared project.

  • The shared template will be listed and ready for use.

EKS Template

  • Click Launch.

  • Provide only the configuration options exposed to the template consumer, such as:

    • Agent
    • Host Cluster
    • vCluster Configuration
    • Namespace Settings
    • Isolation through Network Policies
    • Authentication Parameters

  • All other configurations are pre-configured and set as override: Not Allowed to ensure a simple and streamlined experience for the end user.

Launch Template

Deleting/Destroying the vCluster

  • Navigate to the environment of the created vCluster.
  • Click Destroy and confirm the action by selecting Yes.
  • This will delete the vCluster along with all dependent resources created as part of the cluster.

Conclusion

By following these steps, you have successfully:

  • Selected and shared the Multi Tenancy system template.
  • Used the template to do Lifecycle Management of vCluster.

These system templates simplify vCluster management, ensure compliance with organizational standards, and provide flexibility for specific workflows.