Using CLI

Using vCluster CLI is the preferred way to deploy vCluster Platform to a Kubernetes cluster. If you decide later on you want to manage your vCluster Platform instance via GitOps, you may export the applied Kubernetes manifests or Helm chart configuration and store this data in a git repository.

1. Download and Install vCluster CLI

Use one of the following commands to download the vCluster CLI binary from GitHub:

Homebrew

brew install loft-sh/tap/vcluster

The binaries in the tap are signed using the Sigstore framework for enhanced security.

Mac (Intel/AMD)

curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

Mac (Silicon/ARM)

curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-darwin-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

Linux (AMD)

curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-linux-amd64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

Linux (ARM)

curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-linux-arm64" && sudo install -c -m 0755 vcluster /usr/local/bin && rm -f vcluster

Download Binary

Download the binary for your platform from the GitHub Releases page and add this binary to your $PATH.

Windows Powershell

md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12';
Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-windows-amd64.exe" -o $Env:APPDATA\vcluster\vcluster.exe;
$env:Path += ";" + $Env:APPDATA + "\vcluster";
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);

Reboot Required

You may need to reboot your computer to use the CLI due to changes to the PATH variable (see below).

Check Environment Variable $PATH

Line 4 of this install script adds the install directory %APPDATA%\vcluster to the $PATHenvironment variable. This is only effective for the current Powershell session, i.e. when opening a new terminal window,vcluster may not be found.

Make sure to add the folder %APPDATA%\vcluster to the PATH environment variable after installing vcluster CLI via Powershell. Afterward, a reboot might be necessary.

Confirm that you've installed the correct version of the vCluster CLI.

vcluster --version

2. Deploy the vCluster Platform

Prerequisites

Please make sure you meet the following requirements before running this command:

1. Current kube-context has admin access to the cluster
2. Helm v3 must be installed
3. kubectl must be installed

Confirm that you are using the correct host cluster kube-context via kubectl config current-context and then run:

vcluster platform start

This will deploy vCluster Platform into the host vcluster-platform namespace. The UI will automatically open in your browser and log you in. You will be asked for your user details to create the admin user.

Troubleshooting

Your vCluster Platform pod is not starting or the UI is not showing up? View the Troubleshooting Guide if you have any issues.

3. Logging in

While vcluster platform start logs you in automatically, you can also manually login via the CLI:

vcluster login https://1rtjxak.loft.host      # See `vcluster platform start` output for login credentials and your actual sub-domain name (auto-generated).

This command will open the browser where you can sign in using the login data shown in the output of vcluster platform start.

4. Create Virtual Clusters

After logging into the UI, you'll be able to start creating virtual clusters immediately. You're automatically part of a project called Default Project.

Click on "New Virtual Cluster" and "Create" to spin one up to try out.

Otherwise, read more about some primary concepts:

• Projects - How resources can be grouped together into different projects
• Virtual Clusters - How to create and manage virtual clusters
• Templates - How to use templates to control what type of resources that can be made
• Host Clusters - How to add more host clusters to the platform