Deploying Eclipse Che on K3s
A non-exhaustive guide

Backstory

I recently spent an entire weekend deploying Eclipse Che on a K3s cluster using Keycloak as an OIDC provider. Although it was a lot of fun, I was suprised by the lack of documentation and tutorials on this topic. So, to save you some time and frustration, I decided to write a guide on how to do it.

Prequisites

Before you start, make sure you have the following:

• A K3s cluster up and running
• Traefik installed as your ingress controller (if not already available through K3s)
• A domain pointing to your K3s cluster's IP address
• An SSL certificate for your chosen domain (ideally a wildcard subdomain certificate)
• chectl installed on the machine running the cluster

Step 1: Deploying Keycloak

First things first, we'll create the necessary files to deploy Keycloak:

Copy codetouch keycloak-namespace.yaml keycloak-chart.yaml keycloak-ingress.yaml

Kubernetes namespaces help organize resources. Let's create one for Keycloak:

Copy codeapiVersion: v1
kind: Namespace
metadata:
  name: keycloak

Run this command to apply the YAML:

Copy codekubectl apply -f keycloak-namespace.yaml

Now we're ready to install Keycloak using Helm. K3s comes with a built-in Helm controller, which we will use for the installation. Be sure to configure the credentials for the default admin user in the valuesContent section.

Copy codeapiVersion: Helm.cattle.io/v1
kind: HelmChart
metadata:
  name: keycloak
  namespace: kube-system
spec:
  repo: https://charts.bitnami.com/bitnami
  chart: keycloak
  targetNamespace: keycloak
  valuesContent: |-
    auth:
      adminUser: admin
      adminPassword: admin
    ingress:
      enabled: false
    proxy: edge
    production: true

Copy codekubectl apply -f keycloak-chart.yaml

Since we disabled ingress in the Helm chart, let's create a Traefik IngressRoute to make Keycloak accessible externally. Don't forget to replace keycloak.example.com with your domain.

Copy codeapiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak-ingress
  namespace: keycloak
  annotations:
    traefik.ingress.kubernetes.io/redirect-entry-point: https
spec:
  ingressClassName: traefik
  tls:
    - hosts:
        - keycloak.example.com
  rules:
    - host: keycloak.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: keycloak
                port:
                  number: 80

Apply the Ingress definition:

Copy codekubectl apply -f keycloak-ingress.yaml

If everything goes smoothly, you should be able to access Keycloak at https://keycloak.example.com. Log in using the credentials you set in the valuesContent section.

Drag or press Enter to zoom in on the image

Step 2: Configuring Keycloak

To configure Keycloak as an OIDC provider, we'll create a new realm (think of it as an authentication zone) and a client specifically for Eclipse Che.

Creating a new realm

1. Log in to the Keycloak admin dashboard.
2. Click the dropdown menu "master" in the top left corner and select Add realm.
3. Give your realm a name and click Create.

Creating a new client

1. In the left sidebar, navigate to Clients.
2. Click Create Client.
3. Assign a name to your client and configure the settings as shown in the image (you can zoom in for a closer look).

Drag or press Enter to zoom in on the image

Step 3: Configuring K3s to use Keycloak as an OIDC provider

Now, we need to tell K3s to leverage Keycloak for OIDC authentication. Edit (or create) the K3s configuration file located at /etc/rancher/k3s/config.yaml and add the following lines, replacing placeholders with your actual values:

Copy codekube-apiserver-arg:
  - "oidc-issuer-url=https://keycloak.example.com/realms/your-realm-name"
  - "oidc-client-id=eclipse-che"
  - "oidc-username-claim=email"

Once you've added those lines, apply the changes by restarting the K3s server:

Copy codesystemctl restart k3s

This particular part of the setup has already been documented here and here. I recomment following these guides if you are not familiar with Keycloak.

Step 4: Deploying Eclipse Che

We're almost there! Now, let's deploy Eclipse Che using chectl, a tool specifically designed for this purpose on Kubernetes. It's generally considered simpler than Helm for Che deployments.

We'll need two YAML files to configure and deploy Che:

Copy codetouch che-cluster.yaml che-ingress.yaml

The che-cluster.yaml file defines how Che interacts with Keycloak. Here, we specify Keycloak as the OIDC provider and email as the username claim:

Copy codekind: CheCluster
apiVersion: org.eclipse.che/v2
spec:
  networking:
    auth:
      externalIdentityProvider: true
      openShiftoAuth: false
      oAuthClientName: eclipse-che
      oAuthSecret: eclipse-che
      identityProviderURL: "https://keycloak.example.com/realms/your-realm"
  components:
    cheServer:
      extraProperties:
        CHE_OIDC_USERNAME__CLAIM: email

The ingress file is similar to the Keycloak ingress file, defining how to access the Che web interface:

Copy codeapiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: eclipse-che-ingress
  namespace: eclipse-che
spec:
  rules:
    - host: che.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: che-gateway
                port:
                  number: 8080

Run the following command to deploy Che using chectl. Remember to replace placeholders with your actual domain and configuration file:

Copy codechectl server:deploy --domain che.example.com --platform k8s --che-operator-cr-patch-yaml che-cluster.yaml --skip-cert-manager

Once all pods are running, apply the ingress definition to make Che externally accessible:

Copy codekubectl apply -f che-ingress.yaml

And that's it! You should now be able to access Eclipse Che at https://che.example.com.

Drag or press Enter to zoom in on the image