Skip to main content

Install vCluster Platform With Helm

The platform can be installed directly using Helm commands. Managing the platform installation with Helm directly can be a great way to "GitOps" your platform installation, by using ArgoCD or other GitOps tools to manage the platform deployment. This section outlines the basics of installing and managing the platform with Helm, and can serve as a solid starting point for managing the platform in a GitOps fashion as well.

Prerequisites​

The platform installation via Helm is similar to any Helm chart installation.

Adding the Loft helm repository​

If you haven't done so, add the Loft Helm repository and update.

Add Loft helm repository
helm repo add loft https://charts.loft.sh
helm repo update
tip

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

List available platform versions
helm search repo loft-sh/vcluster-platform

Installing the platform helm chart​

Install the platform
RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform
PLATFORM_VERSION='' # Set this to a specific version or leave empty to install the latest version

helm upgrade $RELEASE_NAME vcluster-platform \
  --install \
  --repo https://charts.loft.sh/ \
  --namespace $RELEASE_NAMESPACE \
  --create-namespace \
  ${PLATFORM_VERSION:+--version $PLATFORM_VERSION}

You should see output similar to the following:

Release "vcluster-platform" does not exist. Installing it now.
NAME: vcluster-platform
LAST DEPLOYED: Fri Oct  4 13:10:52 2024
NAMESPACE: vcluster-platform
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Thank you for installing vcluster-platform.

Values.yaml​

As with most Helm charts, the vcluster-platform chart supports many user-configurable values to modify the deployment of resources. You can find the vcluster-platform chart in the Loft public repository here. The values.yaml file in the chart repository contains the default values, as well as many comments showing optional values and additional information.

To customize your installation, you can either:

  1. Copy the default values file and modify it to suit your deployment needs, or
  2. Create a new YAML file containing only the desired values settings.

Config field in values.yaml​

Inside the values.yaml file, there is a config field, which contains the configuration options for the platform. These options are available in the UI under Admin > Config section and can be edited either through the values.yaml or the UI. There is a detailed list of available configuration options in the docs.

There are a set of fields in the values.yaml that are recommended to explicitly set:

  • config.loftHost - Sets a publicly resolvable hostname.
  • admin.username - Sets the username of an administrator user. By default, the username is admin.
  • admin.password - Sets the password of an administrator user. By default, the username is password.
Recommended values.yaml and config section.
admin:
  username: my-own-username
  password: my-unique-password
config:
  audit:
    enabled: true
  loftHost: vcluster-platform.mytld.com

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

Installing with a values.yaml​

Values files can be passed to the Helm upgrade command. Update $PLATFORM_VERSION with a valid vCluster Platform version.

Install with custom values.yaml.
RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform
PLATFORM_VERSION='' # Set this to a specific version or leave empty to install the latest version

helm upgrade $RELEASE_NAME vcluster-platform \
  --install \
  --repo https://charts.loft.sh/ \
  --namespace $RELEASE_NAMESPACE \
  --create-namespace \
  --values values.yaml \
  ${PLATFORM_VERSION:+--version $PLATFORM_VERSION}

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

Helm has many additional flags and other ways to pass values. As always, it's a great idea to check out the Helm docs to stay up to date on Helm.

Log in to the platform​

If the loftHost is not configured in the platform settings, a random domain is automatically provisioned. You can retrieve this domain from the loft-router-domain secret located in the installation namespace. This domain is essential for accessing the platform interface and configuring other services.

info

You can easily configure your own custom domain.

Follow these steps to retrieve the domain name from the secret:

To retrieve the domain from the secret on Linux, run:

Retrieve domain value.
# Set the namespace where the platform is installed
PLATFORM_NAMESPACE=vcluster-platform

echo "https://$(kubectl get secret loft-router-domain \
  -n "$PLATFORM_NAMESPACE" \
  -o jsonpath="{.data.domain}" \
  | base64 --decode)"
note

If you encounter an error or the secret is not found, ensure that the platform is properly installed and that you have the necessary permissions to access secrets in the specified namespace.

Default credentials​

If the username and password are not set in your values.yaml, the default credentials are:

  • Username: admin
  • Password: my-password
info

It is strongly recommended to change these default credentials for security reasons. You can reset the administrator password.

Navigate to the domain in your browser and log in with the default credentials or the credentials you set in values.yaml and complete the profile setup.

Uninstalling the platform​

If you need to uninstall the platform, follow these steps:

Uninstall the platform.
# Set the namespace variable
PLATFORM_NAMESPACE=vcluster-platform

# Uninstall the Helm release
helm uninstall vcluster-platform -n $PLATFORM_NAMESPACE
danger

Uninstalling the platform deletes all associated resources and data. Ensure you back up any important information before proceeding with the uninstallation.