Deploying Plethos using the official Helm chart

Deploy Plethos on your Kubernetes cluster using the official Helm chart. This guide covers the required infrastructure, initial installation, configuration and upgrades.

Prerequisites

Before deploying Plethos, make sure the following infrastructure is available.

Kubernetes cluster: A Kubernetes cluster which will serve as the host cluster for Plethos.
Ingress controller: An ingress controller that supports SSL passthrough, e.g. ingress-nginx configured with --enable-ssl-passthrough.
Identity provider: An OpenID Connect (OIDC)-compatible identity provider for authentication.
SMTP server: The portal sends emails to users, so it needs an SMTP server to send them through.
DNS for the portal: A DNS record for the portal’s hostname, pointing to your ingress controller.
DNS for virtual clusters: Each virtual cluster exposes its own Kubernetes API endpoint. Configure a wildcard DNS record for *.<your-vcluster-domain> so every virtual cluster is reachable through its own hostname. No certificate is needed, each vCluster serves its own through SSL passthrough.
DNS and TLS for exposed applications (optional): To make applications deployed inside your users’ vClusters publicly accessible, configure a separate wildcard DNS record for *.<your-apps-domain>. Also configure a wildcard TLS certificate covering *.<your-apps-domain> as the ingress controller’s default certificate.

Installation

Download the default configuration

Choose the chart version you want to install and export its default configuration values to a local file.
Terminal
```
helm show values oci://codeberg.org/hmcloudlabs/plethos \
  --version <version> > values.yaml
```
Configure your deployment

Edit values.yaml to match your environment. Review all settings carefully, especially domain names, URLs, OIDC configuration and email settings. Replace placeholder values such as example.com, admin@example.com and localhost URLs before deploying.

For a detailed explanation of every values.yaml configuration, see the Helm chart configuration page.
Create a Namespace for Plethos

Create a Namespace with the name of your choice. The rest of the guide will use plethos.
Terminal
```
kubectl create ns plethos
```

Create the portal secrets

Create the Kubernetes Secret containing the portal’s session, CSRF, OIDC and optional SMTP credentials.

kubectl create secret generic plethos-portal-secrets \
  --namespace plethos \
  --from-literal=PORTAL_SESSION_SECRET="$(openssl rand -hex 32)" \
  --from-literal=CSRF_TOKEN_SECRET="$(openssl rand -hex 32)" \
  --from-literal=OIDC_CLIENT_SECRET="<your OIDC client secret>" \
  --from-literal=SMTP_USERNAME="<your SMTP username>" \
  --from-literal=SMTP_PASSWORD="<your SMTP password>"

SMTP_USERNAME and SMTP_PASSWORD are optional. Omit both options if your SMTP server does not require authentication.

Install Plethos

Install the chart into your chosen namespace with the release name plethos. See the releases on Codeberg to find the latest version.
Terminal
```
helm install plethos oci://codeberg.org/hmcloudlabs/plethos \
  --version <version> \
  --namespace plethos \
  --values values.yaml
```

Upgrading

To upgrade an existing installation, update your local values.yaml if necessary and run helm upgrade with the desired chart version.

helm upgrade plethos oci://codeberg.org/hmcloudlabs/plethos \
  --version <version> \
  --namespace plethos \
  --values values.yaml

Helm does not automatically upgrade CRDs stored in a chart’s crds/ directory. If a new Plethos release changes the VClusterClaim CRD, apply the updated definition manually before upgrading the chart.

helm show crds oci://codeberg.org/hmcloudlabs/plethos \
  --version <version> | kubectl apply -f -