Quick Start Guide
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
- Mac (Intel/AMD)
- Mac (Silicon/ARM)
- Linux (AMD)
- Linux (ARM)
- Windows Powershell
brew install loft-sh/tap/vcluster
If you installed the CLI using brew install 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.
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
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
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
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
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);
You may need to reboot your computer to use the CLI due to changes to the PATH variable (see below).
Line 4 of this install script adds the install directory %APPDATA%\vcluster
to the $PATH
environment 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
2. Deploy the vCluster Platform
Please make sure you meet the following requirements before running this command:
- Current kube-context has admin access to the cluster
- Helm v3 must be installed
- 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.
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 vClusters
Let's now create a vCluster called my-vcluster-pro
in the my-vcluster-pro-namespace
namespace, via the vCluster CLI:
vcluster create my-vcluster-pro --namespace my-vcluster-pro-namespace
This command creates a virtual cluster.