Skip to main content

Deploy using CLI

The vCluster CLI is the preferred method for deploying the platform to a Kubernetes cluster. It streamlines the deployment 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​

  • Administrator access to a Kubernetes cluster: See Accessing Clusters with kubectl for more information. Your current kube-context must have administrative privileges, which you can verify with kubectl auth can-i create clusterrole -A

    info

    To obtain a kube-context with admin access, ensure you have the necessary credentials and permissions for your Kubernetes cluster. This typically involves using kubectl config commands or authenticating through your cloud provider's CLI tools.

  • helm installed: Helm v3.10 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.

Deployment​

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.

Configuration​

The vcluster CLI offers various configuration options to customize the deployment process.

Non-default Kubernetes cluster​

By default, the platform is deployed to the current Kubernetes context.

Get the current Kubernetes context
kubectl config current-context

This can be overridden by specifying the --context flag:

Deploy the platform to a specific Kubernetes context
vcluster platform start --context my-cluster

Custom namespace​

By default, the platform is deployed to the vcluster-platform namespace. This can be changed by specifying the --namespace flag:

Deploy the platform to a custom namespace
vcluster platform start --namespace my-namespace
info

If the specified namespace does not exist, it is created automatically.

Different platform version​

The vCluster CLI uses the latest version of the platform Helm chart by default. To use a specific version, specify the --version flag:

tip

To retrieve all available versions of the platform Helm chart, run the following command:

List available platform versions
helm search repo loft-sh/vcluster-platform
Deploy the platform using a specific version
vcluster platform start --version 4.0.0-alpha.0
tip

Provide version number without the v prefix. However if you do, the CLI automatically removes it.

info

Refer to the vCluster CLI Reference for more configuration options.

Login​

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.

Next steps​

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