Skip to main content

Deploy using Helm

The platform can be deployed directly using Helm commands. Managing the platform deployment with Helm directly can be a great way to "GitOps" your platform deployment, by using ArgoCD or other GitOps tools to manage the platform deployment. This section outlines the basics of deploying 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​

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

Deployment​

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

Adding the 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

Deploying the platform​

Deploy the platform
RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform
PLATFORM_VERSION='' # Set this to a specific version or leave empty to deploy 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:

Output of the Helm deploy command
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.
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

Configuration​

Customize values​

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 deployment, 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.

Configure platform options​

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

Apply custom configuration​

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

Deploy with custom values.yaml.
RELEASE_NAME=vcluster-platform
RELEASE_NAMESPACE=vcluster-platform
PLATFORM_VERSION='' # Set this to a specific version or leave empty to deploy 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.

Login​

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.

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