Install the vCluster CLI

Learning objectives

In this guide, you learn the following:

1. How to install the vCluster CLI.
2. How to deploy vCluster.
3. How to connect to vCluster and how vCluster interacts with the host cluster.
4. How to uninstall vCluster.

These exercises should take about 10 minutes.

You can join the Loft Users Slack to ask questions in the #vcluster channel.

Terms:

• vCluster: the product; this also refers to a vCluster installation.
• vcluster: the CLI.
• host: The Kubernetes cluster that you install vCluster on.

Before you begin

• You have read What Are Virtual Clusters.
• You have installed kubectl (check via kubectl version) and Helm v3.10.0+ (check with helm version).
• You have access to a Kubernetes cluster to use as the host cluster (check with kubectl get namespaces)

Install the vCluster CLI

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

Homebrew

brew install loft-sh/tap/vcluster

If you installed the CLI using brew install loft-sh/tap/vcluster, you should brew uninstall vcluster and then install using the tap. 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

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.

Alternatively, you can download the binary for your platform from the GitHub Releases page and add this binary to your PATH.

To confirm that vCluster CLI is successfully installed, test via:

vcluster --version