Install vCluster.Pro With Helm

vCluster.Pro can be installed directly via Helm, in fact, even when following the recommend installation procedure in the Getting Started Guide the vCluster.Pro CLI is actually using Helm to install vCluster.Pro!

Managing the vCluster.Pro installation with Helm directly can be a great way to "GitOps" your vCluster.Pro installation, by using ArgoCD or other GitOps tools to manage the vCluster.Pro deployment via Helm and appropriate Helm values. This section outlines the basics of installing and managing vCluster.Pro with Helm, and should serve as a solid starting point for managing vCluster.Pro in a GitOps fashion as well!

Simple Installation

The most basic vCluster.Pro installation via Helm looks like any other Helm install command and can be seen below:

helm upgrade [RELASE NAME] vcluster-control-plane --install \
  --repo https://charts.loft.sh/ \
  --namespace vcluster-pro

Typically, users will simply call the release name vcluster-pro. If the 'vcluster-pro' namespace does not already exist, you can add the --create-namespace flag as well, for a final installation command as follows:

helm upgrade loft vcluster-control-plane --install \
  --repo https://charts.loft.sh/ \
  --namespace vcluster-pro \
  --create-namespace

vCluster.Pro Values

As with most Helm charts, the vCluster.Pro chart supports many user configurable values to modify the installation. You can find the vCluster.Pro chart in the vCluster.Pro public repository here. The values.yaml file in the chart repository contains the default values, as well as many comments showing optional values and some additional information.

Users can copy the default values file and modify it to suite their deployment needs, or create a new YAML file containing only the desired values settings. An example values file myvalues. yaml is outlined below.

config:
  audit:
    enabled: true
  loftHost: vcluster-pro.mytld.com

ingress:
  enabled: true
  host: vcluster-pro.mytld.com

Values files can then be passed to the Helm upgrade command:

helm upgrade loft vcluster-control-plane --install \
  --repo https://charts.loft.sh/ \
  --namespace vcluster-pro \
  --create-namespace \
  --values myvalues.yaml

You can provide multiple values files if desired by specifying additional filenames after the --values flag. This can be handy if you like to break up the values sections into different files.

Helm has many additional flags, and other ways to pass values, as always, its a great idea to check out the Helm docs to stay up to date on Helm!

vCluster.Pro Configuration

The vCluster.Pro Configuration options (as seen in the vCluster.Pro UI Admin > Config section) are configurable via vCluster.Pro Helm values just like any other deployment options. These values are set under the config section of the chart values, you can see the available configuration options in the Configuration Section of the docs here.

While all configuration settings are optional, it is always recommended to deploy vCluster.Pro with the loftHost configuration set. This config option tells vCluster.Pro what its own publicly resolvable hostname is and is necessary for some integrations, including ArgoCD, and SSO.

The vCluster.Pro Agent

Every connected cluster in a vCluster.Pro environment, including the "main" cluster that vCluster.Pro is deployed in, must have a vCluster.Pro Agent deployed. This agent pod handles reconciliation of cluster scoped (as in not vCluster.Pro instance wide) resources.

By default, when vCluster.Pro is installed, the vCluster.Pro pod will also install the vCluster.Pro Agent into the cluster you are deploying vCluster.Pro into. This is usually a desirable behavior since vCluster.Pro requires the Agent to be present in all clusters. Sometimes, however, admins wish to manage the installation of the vCluster.Pro Agent themselves, either by installing it explicitly, or by installing it via GitOps tooling. In this situation, it is possible to disable the Agent deployment by setting the DISABLE_AGENT environment variable to "true". This can be accomplished in the env section of the vCluster.Pro values:

env:
  DISABLE_AGENT: true

It is also possible to tell vCluster.Pro not to install Agents into individual clusters -- this can be accomplished by setting the loft.sh/cluster-ignore-agent Annotation of the Cluster resource to "true" for any clusters that vCluster.Pro should not manage the Agent deployment on.

vCluster.Pro Agent Is Required!

The vCluster.Pro Agent is required for every connected cluster in a vCluster.Pro deployment, this includes the cluster vCluster.Pro itself is deployed into. If you are disabling the agent deployment via one of the mechanism described above, make sure you are still getting an Agent installed into every connected cluster by some other means!

If you are electing to manage the Agent installation yourself, you can install the Agent directly using Helm.

helm upgrade loft-agent vcluster-control-plane --install \
  --repo https://charts.loft.sh/ \
  --namespace vcluster-pro \
  --create-namespace \
  --set agentOnly=true

vCluster.Pro Agent Values

As with the primary vCluster.Pro chart, the vCluster.Pro Agent chart exposes values that can be configured by an administrator to suit their needs. As with the primary vCluster.Pro deployment, the Agent chart and values can be seen in the public repository here.

If you have deployed vCluster.Pro with the default behavior of not disabling the Agent deployment, you can still provide values to influence the deployment of the Agent itself. This can be accomplished by providing any valid Agent values in the agentValues section of the vCluster.Pro chart values. These values are received by the vCluster.Pro deployment and used when deploying the Agent pods! Below is an example of the vCluster.Pro values agentValues section.

agentValues:
  securityContext:
    enabled: true

Administrators can also provide Agent values for specific clusters by setting the loft. sh/agent-values Annotation of a specific cluster object. These values will always override any values provided in the parent vCluster.Pro chart.