Skip to main content

Install vCluster Platform With Helm

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

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

Simple Installation​

The most basic vCluster Platform 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 Platform Values​

As with most Helm charts, the vCluster Platform chart supports many user configurable values to modify the installation. You can find the vCluster Platform chart in the vCluster Platform public repository here. The vcluster.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 Platform Configuration​

The vCluster Platform Configuration options (as seen in the vCluster Platform UI Admin > Config section) are configurable via vCluster Platform 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 Platform with the loftHost configuration set. This config option tells vCluster Platform what its own publicly resolvable hostname is and is necessary for some integrations, including ArgoCD, and SSO.

The vCluster Platform Agent​

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

By default, when vCluster Platform is installed, the vCluster Platform pod will also install the vCluster Platform Agent into the cluster you are deploying vCluster Platform into. This is usually a desirable behavior since vCluster Platform requires the Agent to be present in all clusters. Sometimes, however, admins wish to manage the installation of the vCluster Platform 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 Platform values:

env:
  DISABLE_AGENT: true

It is also possible to tell vCluster Platform 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 Platform should not manage the Agent deployment on.

vCluster Platform Agent Is Required!

The vCluster Platform Agent is required for every connected cluster in a vCluster Platform deployment, this includes the cluster vCluster Platform 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 Platform Agent Values​

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

If you have deployed vCluster Platform 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 Platform chart values. These values are received by the vCluster Platform deployment and used when deploying the Agent pods! Below is an example of the vCluster Platform 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 Platform chart.