Using CLI
The vCluster CLI is the preferred method for deploying the platform to a Kubernetes cluster. It streamlines the installation process and ensures compatibility with your Kubernetes environment. If you later decide to manage your platform instance via GitOps, you can export the applied Kubernetes manifests or Helm chart configuration and store them in a Git repository.
Prerequisites
Before you begin, ensure that you have the following:
- Admin access to a Kubernetes cluster: Your current kube-context must have administrative privileges. See Accessing Clusters with kubectl for more information.
- Helm v3 installed: Helm is required for deploying the platform. Refer to the Helm Installation Guide if you need to install it.
kubectl
installed: Kubernetes command-line tool for interacting with the cluster. See Install and Set Up kubectl for installation instructions.
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)
- Download Binary
- Windows Powershell
brew install loft-sh/tap/vcluster
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
Download the binary for your platform from the GitHub Releases page and add this binary to your $PATH.
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.
Confirm that you've installed the correct version of the vCluster CLI.
vcluster --version
After installation, verify the successful installation of the vCluster CLI by running vcluster version
in your terminal. This command should display the installed version of the vCluster CLI.
Deploy the platform
Before deploying the platform, ensure the correct host cluster kube-context is in use. The host cluster kube-context configures which Kubernetes cluster and namespace kubectl
commands interact with. To confirm the current context, run:
kubectl config current-context
Once you've confirmed the correct context, deploy the platform by running:
vcluster platform start
This command deploys the platform onto the host-cluster in the vcluster-platform
namespace.
The vcluster-platform
namespace is created automatically and serves as a
dedicated space for the platform components.
The UI automatically opens in your browser and logs you in. You are asked for your user details to create the administrator user.
The deployment process typically takes less than 1 minute, but can take up to 2 minutes depending on your cluster's resources and network speed.
You should see output similar to the following:
...
########################## LOGIN ############################
Username: admin
Password: 27177595-21bc-4ff9-9f3a-51e0f722408b # Change via UI or via: vcluster platform reset password
Login via UI: https://hth45c8.loft.host
Login via CLI: vcluster login https://hth45c8.loft.host
#################################################################
vCluster Platform was successfully installed and can now be reached at: https://hth45c8.loft.host
Thanks for using vCluster Platform!
11:38:33 done You are successfully logged into vCluster Platform!
- Use `vcluster platform create vcluster` to create a new virtual cluster
- Use `vcluster platform add vcluster` to add an existing virtual cluster to a vCluster platform instance
After successful deployment, the UI automatically opens in your default web browser. You are prompted to create an administrator user.
If your platform pod is not starting or the UI is not showing up, view the Troubleshooting Guide for assistance.
Logging in
While vcluster platform start
logs you in automatically, you can also manually log in 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 opens the browser for signing in using the login data displayed in the output of vcluster platform start
. Manual login may be necessary if accessing the platform from a different machine or if the automatic login process is interrupted.
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.
Find more information about creating virtual clusters in the create virtual clusters section.
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