Cluster Details & Setup

Ellf lets you plug in your own data processing cluster hosted locally or on your cloud infrastructure and under your control. The cluster provides all data, models and custom code you use and create, and serves the annotation interface and performs actions like model training or data analysis. This means that no sensitive data ever leaves your servers or has to pass through our servers in the process.

The clusters CLI lets you set up and launch your own cluster without requiring specific. infrastructure or DevOps expertise. It also lets you manage your cluster and check its status. In the UI, clicking ClusterSetup will show details and configuration options. In the top bar of the app, you will also see the cluster status:

Installation

Under the hood, the cluster uses Kubernetes and can be installed to run locally on your machine, or in the cloud under your own cloud provider like AWS, GCP or Azure.

Installing the cluster locally

Setting up the cluster on your local machine is the quickest and easiest option to get started. Under the hood, it uses K3s, a lightweight Kubernetes distribution.

Prerequisites

• a Linux machine (bare metal or VM) with at least 4 GB RAM and 20 GB disk
• K3s installed:
  Copy

  $ curl -sfL https://get.k3s.io | sh -

• Helm installed:
  Copy

  $ curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

• the Ellf CLI installed and authenticated

Once K3s is running, make sure your kubeconfig is accessible:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER ~/.kube/config

If your system defaults to the K3s kubeconfig path instead of ~/.kube/config, set the KUBECONFIG variable in your shell profile:

export KUBECONFIG=~/.kube/config

Verify that kubectl can reach the cluster:

Register, configure and deploy

Next, you can use the infra CLI to register your cluster with Ellf. For a local cluster, use localhost as the domain and k3s as the cloud provider.

This writes a cluster-creds.json file with the credentials needed for the next steps. Next, install cert-manager for TLS certificate management:

Generate the Helm values file from your credentials:

Review the generated values.yaml and update the PostgreSQL password, then deploy:

Once the deployment completes, verify the cluster is healthy:

Installing the cluster in the cloud

For a flexible, stable and production-ready workflow, you typically want to host the cluster in the cloud and share it across your organization. This requires you to have access to a project in your cloud provider account, with permission to install new resources.

Google Cloud (GCP)

The CLI includes Terraform support for provisioning GCP infrastructure. First, create a GCP project and authenticate:

Then register and deploy the cluster following the same steps as for a local installation, using gcp as the cloud provider and your cluster’s public domain as the --domain.

For GCP clusters with a public domain, you can use Let’s Encrypt for automatic TLS certificates by passing --acme-email during setup and when generating values:

AWS

TLS & Remote Access

If your cluster is running on a machine without a public domain (e.g. a workstation on your local network), you’ll need TLS and an SSH tunnel to access it from another machine. Modern browsers require HTTPS for features like service workers, the clipboard API and secure WebSocket connections.

Setting up TLS

The CLI can create a self-signed certificate authority (CA) and issue a TLS certificate for your cluster using cert-manager. This is the recommended approach for local clusters where Let’s Encrypt isn’t an option (ACME HTTP-01 challenges require a publicly reachable domain).

This creates a CA and leaf certificate via cert-manager and updates the broker ingress to serve HTTPS. It then prints the commands you need to run to trust the CA on your machine.

To get the trust commands in a format you can pipe directly to your shell:

You can check the current TLS status at any time:

Accessing the cluster over SSH

To access a cluster running on a remote machine from your laptop, open an SSH tunnel that forwards the HTTPS port:

Then point your local CLI at the tunnel:

You can now open https://localhost:8443 in your browser and use the CLI normally. The self-signed CA you installed ensures the browser trusts the certificate without warnings.

Moving chat assistant data to your cluster

When you start using Ellf, the in-app chat logs and artifacts to enable handover to your local coding assistant, are stored in our database. This allows users to get started with project planning immediately and before setting up and installing their cluster. However, once your cluster is running, you can migrate the assistant data.

Worker classes

By default, the cluster is set up to provide the workers base, small, medium and gpu, with the following specs. If you want to define custom workers, you can add them to the config.yml before launching your cluster. The machine types are specific to what’s available via your cloud provider.

Customizing your cluster

Using a custom domain

Because the cluster needs to be available via HTTPS over the internet, it needs to be assigned a domain. By default, Ellf assigns it a subdomain of our domain ellf.run, e.g. yourorg.ellf.run, but you can also use your own custom domain or subdomain instead.

You’ll need access to manage your domain’s DNS and create an A Record pointing your domain or desired subdomain to the public IP of your cloud project. The specifics of how and where to do this will depend on your domain registrar or DNS management solution. You don’t need to worry about the SSL certificate and HTTPS – this will all be taken care of automatically when you launch the cluster.

Once the DNS record is in place, register the cluster with your custom domain and deploy with Let’s Encrypt for automatic certificate management:

Generate the values file with your domain and ACME email, then deploy. The SSL certificate will be provisioned automatically on first deploy.

Using multiple clusters Advanced usage

For most use cases, a single data processing cluster is sufficient and keeps your setup simple. However, for advanced use cases, it’s possible to connect more than one cluster to your Ellf organization. This gives you more control over where and how your data is stored, including using different cloud providers for different data, projects and privacy requirements. It also lets you manage permissions separately, e.g. to give users and developers only access to certain data.

To add a second cluster, run infra register with a different name and domain. Each cluster gets its own credentials file and values configuration:

After successful setup, you should now see a dropdown menu for the cluster status in the top bar, which lets you switch between the available clusters.