Skip to main content

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:

brew install loft-sh/tap/vcluster

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

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

vcluster --version
tip

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:

Get the current Kubernetes context
kubectl config current-context

Once you've confirmed the correct context, deploy the platform by running:

Deploy the platform
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.

info

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:

Platform installation output
...

##########################   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.

Troubleshooting

If your platform pod is not starting or the UI is not showing up, view the Troubleshooting Guide for assistance.

Log in to the platform​

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

Platform login
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.

tip

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