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. See this table for an overview of which data is stored where.

The infra and clusters CLI lets you set up and launch your own cluster without requiring deep 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:

Your cluster is now live and connected to Ellf – you’ll see it in the top bar of the app.

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. Setup is three commands – init, provision and start – and everything in between (registration, domain allocation, the cluster config, copying Terraform outputs around) is handled for you. If you have an existing infrastructure pipeline or want to hand over the installation to your infrastructure team, see the notes on using your own Terraform pipeline.

Prerequisites

• access to a project in your cloud provider account, with permission to create resources
• an authenticated cloud CLI: gcloud for GCP, aws for AWS, az for Azure
• Terraform, kubectl and Helm installed
• the Ellf CLI installed and authenticated

1. Initialize

Pick an empty directory for your cluster files and run infra init. Anything you omit is asked for interactively, including a Terraform state bucket, which you should accept.

This registers the cluster with Ellf, automatically assigns it a subdomain of our domain ellf.run (e.g. yourorg.ellf.run, or you can use your own domain), downloads the Terraform files and generates config.yaml. It’s safe to re-run at any time.

2. Provision the infrastructure

If your Terraform is applied by an infrastructure team or your own pipeline, skip this step and see the docs on using your own Terraform pipeline.

This shows you the Terraform plan and applies it on confirmation. Everything the infrastructure produces – database address, container registry, ingress IP – is synced into config.yaml automatically, and your cluster’s DNS records are pointed at the new ingress. Expect the apply to take a while (10–20 minutes) on the first run.

3. Enable TLS

For automatic HTTPS certificates via Let’s Encrypt, add your ACME email to config.yaml:

deployment:
  acme_email: you@yourdomain.com
  tls_secret_name: cluster-tls

4. Start the cluster

This fetches kubectl credentials, installs Traefik and cert-manager, and deploys the cluster services. Once it completes, verify the cluster is healthy:

Your cluster is now live at its domain and connected to Ellf – you’ll see it in the top bar of the app. To change any setting later (provider inputs, state backend, domain values), edit config.yaml or run infra configure, then re-run provision and/or start to apply.

Terraform state

Terraform tracks everything it created in a state file, and losing it means losing the ability to manage or cleanly destroy the cluster. The CLI therefore requires a state location before it will run Terraform – the versioned bucket that init offers to create is the recommended one, and a Terraform Cloud workspace or an explicit local-state opt-out (terraform: { local: true }, for throwaway clusters) also work.

The bucket deliberately lives outside the Terraform: it must exist before Terraform runs, and infra destroy never touches it, because the destroy itself needs the state it holds. Only delete it manually, after the cluster is gone for good.

Using your own Terraform pipeline

If you want to integrate the cluster into your existing infrastructure setup or have your DevOps team take over the installation, you can hand over the directory generated by the initialization step. This bundle includes the config.yaml, the provider Terraform directory and terraform.tfvars.json. Your team can then apply it however you normally apply Terraform, then sync the outputs back instead of running the provision step:

This runs terraform output (remote state works), fills config.yaml and points the DNS, exactly as provision would have. Then continue with starting the cluster.

Other cloud providers

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. When you initialize a cluster without --domain, Ellf assigns it a subdomain of our domain ellf.run for this purpose, but the cluster itself still runs on your machine or cloud.

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 override the cluster URL the CLI dials for the current shell. ELLF_BROKER_HOST only changes which address the CLI talks to – the cluster you logged into (its cluster_id) is still resolved against the central API server, so token exchange works against the right cluster:

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, project plans 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. The machine types are specific to what’s available via your cloud provider and can also be customized.

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. When you run infra init (or infra register) without --domain, Ellf allocates it a subdomain of our domain ellf.run, e.g. yourorg.ellf.run, and points its DNS records at the cluster automatically once the ingress address exists. But you can also use your own custom domain or subdomain instead by passing it as --domain:

With your own domain, you manage the DNS: create an A Record pointing your domain or desired subdomain to the cluster’s public IP – on GCP it’s synced into config.yaml as deployment.public_ip by infra provision. Elsewhere infra start prints the load balancer address. 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 – set acme_email in config.yaml and it’s taken care of when you start the cluster.

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 init in a separate directory with a different name (and optionally domain). Each cluster gets its own credentials file and 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. When you run login on the CLI, you’ll also be prompted to select the cluster to connect to.