This guide explains how to install Theia Cloud on your cluster.

We recommend using Helm, the package manager for Kubernetes, for managing installations. If you are unfamiliar with Helm, please have a look at their homepage helm.sh first.

Required Software

Theia Cloud depends on well-established software in the Kubernetes ecosystem. We won’t go into full detail explaining how to install each dependency but will provide links to their official documentation.

Please note that our Try Theia Cloud guides use Terraform charts that will install all requirements automatically. Please have a look at their Helm configuration to find the values used in the getting started guides.

cert-manager.io

For certificate management, we use cert-manager.io.

We offer the installation of two cluster issuers: a self-signed issuer for testing and cluster internal usage, and an issuer for creating Let’s Encrypt certificates. You may use your existing cluster issuers as well!

We suggest installing the cert-manager using the official Helm chart.

ingress-nginx

By default, the ingresses are installed via the Theia Cloud Helm charts and created by the Theia Cloud operator using the Ingress NGINX Controller.

You can find the official deployment instructions here.

Note: Since ingress-nginx version 1.10 , the annotation nginx.ingress.kubernetes.io/configuration-snippet is disabled by default and needs to be enabled. To enable this option, set the allow-snippet-annotations: "true" flag in the ingress-nginx values. For example, via the ingress-nginx-controllers config-map. For more information see the documentation

Please note that it is possible to integrate other types of ingresses into Theia Cloud as well, and this is part of our roadmap. We do not offer documentation and finalized APIs for this yet, however. If you need this feature sooner, please see our available support options.

Keycloak (optional)

If your use case requires user management, we recommend the use of Keycloak. Keycloak acts as an OAuth2 provider, and it is possible to integrate other existing providers into Keycloak.

We suggest using the Bitnami Helm chart for the Keycloak installation.

Please note that it is possible to integrate any OAuth2 provider with Theia Cloud, and this is part of our roadmap. We do not offer documentation and finalized APIs for this yet, however. If you need this feature sooner, please see our available support options.

Theia Cloud Helm Charts

Theia Cloud offers three Helm charts that are available via the Helm repository hosted at https://eclipse-theia.github.io/theia-cloud-helm/. These charts are designed to provide a flexible and customizable deployment of Theia Cloud on Kubernetes clusters. The available charts are:

• theia-cloud-base: Installs cluster-wide resources such as issuers and roles used by Theia Cloud.
• theia-cloud-crds: Deploys Theia Cloud Custom Resource Definitions (CRDs) and their conversion webhook.
• theia-cloud: The main Helm chart, including the Operator and Service components for Theia Cloud.

To add the Theia Cloud Helm repository for access to these charts, use the following command:

helm repo add theia-cloud-repo https://eclipse-theia.github.io/theia-cloud-helm/

If you have previously added this repository, ensure you have the latest charts by updating the repository:

helm repo update

Note: You might have added the repository with the old url (https://github.eclipsesource.com/theia-cloud-helm) before. If this is the case, please remove the old repo and re-add it with the new url above.

We aim to make the contents of these charts as customizable as possible. This includes providing options to skip any optional resources during installation. This guide provides an overview of each Helm chart along with sample configurations. For comprehensive configuration options, refer to the linked documentation within each section. Additionally, explore our Terraform configurations for complete Theia Cloud setups on various cluster providers, including GKE and Minikube. For early access to customization options, new terraform examples, or if you require specific changes, please consult our support options.

theia-cloud-base

This chart installs cluster-wide resources necessary for Theia Cloud’s operation. Currently, it includes two ClusterIssuer resources for certificate management and two ClusterRole resources for the Theia Cloud Operator and Service.

To install, first create a base-values.yaml file with your email address:

issuer:
  email: j.doe@theia-cloud.io

Install the chart using:

helm install my-theia-cloud-base theia-cloud-repo/theia-cloud-base -f base-values.yaml

For a full list of customizable values, visit theia-cloud-base chart documentation.

theia-cloud-crds

This chart focuses on Theia Cloud’s CRDs and includes a service for version migration. It’s essential for maintaining custom resources within your cluster.

Installation commands:

kubectl create namespace my-namespace
helm -n my-namespace install my-theia-cloud-crds theia-cloud-repo/theia-cloud-crds

Refer to theia-cloud-crds chart documentation for customization details.

theia-cloud

The main Theia Cloud chart installs the Operator and Service in your chosen namespace. Begin by creating a values.yaml file with your desired configuration, e.g.:

app:
  id: asdfghjkl
  name: My Theia

demoApplication:
  name: theiacloud/theia-cloud-demo
  timeout: "30"

hosts:
  usePaths: true
  configuration:
    baseHost: 12.345.67.89.sslip.io

keycloak:
  enable: false

operator:
  cloudProvider: "K8S"

ingress:
  clusterIssuer: letsencrypt-prod
  theiaCloudCommonName: false
  addTLSSecretName: false

operatorrole:
  name: operator-api-access

servicerole:
  name: service-api-access

Customization Instructions:

• app.id: Generate a unique string for app.id. This identifier is public, so don’t reuse a secret.
• Image Configuration: demoApplication.name allows you to specify a custom Docker image for Theia. Use demoApplication.timeout to define the session timeout, after which the application will automatically shut down.
• Host Configuration: The hosts.configuration.baseHost value has to be set to the hostname you want to use. An easy way to get started could be the public IP of your ingress controller. For example you may get this with:

kubectl -n ingress-nginx get service ingress-nginx-controller -o yaml

# check the status for the public ip
status:
  loadBalancer:
    ingress:
      - ip: 12.345.67.89

# When using a minikube cluster, you may use
minikube ip

• Keycloak Integration: By setting keycloak.enable to false, you opt out of Keycloak integration. If you wish to utilize Keycloak for authentication, further configuration will be necessary. Please check out the options here to learn about all Keycloak options.
  For configuring Keycloak itself please have a look at the oauth2-proxy documentation and our terraform Keycloak Example Realm configuration.
• Cloud Provider Configuration: Adjust operator.cloudProvider to MINIKUBE if running on Minikube or leave the current value K8S for other clusters.
• Ingress and Security: ingress.clusterIssuer may have to be adjusted if a different issuer than the Let’s encrypt issuer should be used or if it was installed with a different name. ingress.theiaCloudCommonName may have to be adjusted if the certificate created by the issuer misses the common name property.
• Roles Configuration: operatorrole and servicerole names might need adjustments if you adjusted the name during the base chart installation

After adjusting the values to your needs, install Theia Cloud with:

helm -n my-namespace install my-theia-cloud theia-cloud-repo/theia-cloud -f values.yaml

This setup enables access to the Theia Cloud sample landing page at https://12.345.67.89.sslip.io/trynow/.

For detailed installation instructions and customization options, visit the main Theia Cloud chart documentation.

Update Theia Cloud

This section explains how to update your Theia Cloud deployment. This includes updating values as well as upgrading to a new Theia Cloud version. Similar to the installation, Helm is used for this.

Before moving to a new Theia Cloud version, you might want to have a look at the Theia Cloud Helm changelog. If you customized core components (e.g. the operator), you also might want to look at Theia Cloud’s code changelog.

Make sure you have the Theia Cloud helm charts available and updated as described in section Theia Cloud Helm Charts. In short:

# First time only
helm repo add theia-cloud-repo https://eclipse-theia.github.io/theia-cloud-helm

# Update the helm repo
helm repo update

You may inspect the available chart versions with:

helm search repo theia-cloud-repo --versions

For the following update steps, we assume that you named your values files and Helm installations as in section Theia Cloud Helm Charts.

Note: Even if you only want to update the values of your Theia Cloud installation, Helm upgrades to the latest version of the chart by default. To stay on the current version or upgrade to a specific version, use the --version option of helm upgrade. For more information see the official Helm upgrade documentation: https://helm.sh/docs/helm/helm_upgrade/.

Instructions to upgrade the charts:

# Base chart
helm upgrade my-theia-cloud-base theia-cloud-repo/theia-cloud-base -f base-values.yaml

# CRD chart
helm -n my-namespace upgrade my-theia-cloud-crds theia-cloud-repo/theia-cloud-crds

# Main chart
helm -n my-namespace upgrade my-theia-cloud theia-cloud-repo/theia-cloud -f values.yaml

Instructions to upgrade the charts to a specific Theia Cloud version (here 0.10.0):

# Base chart
helm upgrade my-theia-cloud-base theia-cloud-repo/theia-cloud-base -f base-values.yaml --version 0.10.0

# CRD chart
helm -n my-namespace upgrade my-theia-cloud-crds theia-cloud-repo/theia-cloud-crds --version 0.10.0

# Main chart
helm -n my-namespace upgrade my-theia-cloud theia-cloud-repo/theia-cloud -f values.yaml --version 0.10.0