Helm guide
These instructions explain how to install and run Feldera Enterprise
on a Kubernetes cluster. It requires a valid Feldera Enterprise license
-- please request one at learnmore@feldera.com if you are interested.
Prerequisites
-
kubectl:
kubectl versionUsed to interact with the Kubernetes cluster
-
helm:
helm versionPackage manager to conveniently manage deployments on Kubernetes
-
Feldera license, notably the account id and license key. They are required in the installation. Please reach out to us at
learnmore@feldera.comif you are interested. -
The Feldera Helm chart and Docker images are hosted on AWS ECR public registry. We will use the chart and multi-arch images by referring to their online repository naming
public.ecr.aws/feldera/<image>:<version>.
Kubernetes Cluster Configuration
Node Sizing
| Resource | Recommendation |
|---|---|
| CPU | 32–48 CPUs per node |
| RAM | At least 32 GiB per node |
By default, the Feldera control plane and pipelines run on the same nodes. Use nodeSelectors to run them on different nodes or node types.
RAM requirements vary by workload. See the memory usage documentation for detailed guidance.
Persistent Volume Sizing
Persistent volumes should meet the following specifications:
- Volume Size: At least the size of the input data. Feldera stores state to perform incremental computations, so the volume must be large enough to hold it. Users can expand pipeline storage on demand.
- IOPS: At least 16,000
- Throughput: At least 1,000 MB/s
Recommended disk types by cloud provider:
| Cloud Provider | Disk Type |
|---|---|
| AWS | gp3 |
| Azure | Ultra Disk |
| GCP | Hyperdisk Balanced |
Installing Feldera Enterprise
-
Kubernetes access: check that your
kubectlis configured to your Kubernetes cluster.kubectl cluster-info
kubectl get namespace -
Version: Visit https://gallery.ecr.aws/feldera/feldera-chart, click on the "Image tags" tab for a list of versions, and choose a version. The most recent version should be at the top of the list and is normally the right choice.
-
Installation: we use our Helm chart, which internally refers to the other images, to perform the installation in namespace
felderawith release namefeldera.ACCOUNT_ID="00000000-0000-0000-0000-000000000000" # Set to own
LICENSE_KEY="00000000-0000-0000-0000-000000000000" # Set to own
VERSION=0.88.0 # Replace with previously chosen version
helm upgrade --install feldera \
oci://public.ecr.aws/feldera/feldera-chart --version "${VERSION}" \
--namespace feldera --create-namespace \
--set felderaVersion="${VERSION}" \
--set felderaAccountId="${ACCOUNT_ID}" \
--set felderaLicenseKey="${LICENSE_KEY}" \
--set felderaDatabaseSecretRef="feldera-db-insecure-secret"Note: the license verification is done by interacting with our online license server at
cloud.feldera.com.Note: how to configure your own database credentials is explained in a further section.
-
Check: check the status of the deployment.
kubectl get pods -n feldera... which should output approximately the following:
NAME READY STATUS RESTARTS AGE
feldera-db-0 1/1 Running 0 3m9s
feldera-kubernetes-runner-6447b8f56d-86j4w 1/1 Running 0 3m9s
feldera-compiler-server-0 1/1 Running 0 3m9s
feldera-api-server-c546499bc-wdpkm 1/1 Running 0 3m9s -
Usage:
Interaction with Feldera happens through the API server, which has an associated service named
<release name>-api-server.<namespace>.svc.cluster.local:8080. With kubectl, this can be port-forwarded to be accessible locally:kubectl port-forward -n feldera svc/feldera-api-server 8080:8080... after which you can (leaving the forwarding running in a terminal):
- Visit Web Console in browser: http://127.0.0.1:8080
- Interact with the API: http://127.0.0.1:8080/v0/...
Note: access through kubectl port-forwarding is mostly useful for test and development. In other cases, setting up an ingress (e.g., in EKS) is likely preferable.
Extra
Retrieving the Feldera values file
The values.yaml file can be retrieved for an existing Feldera release or from the remote Feldera registry.
Remote Feldera registry: Run helm show values oci://public.ecr.aws/feldera/feldera-chart --version {version} >> values.yaml where version is the Feldera platform version for which you want to retrieve values.
Existing Feldera release: Run helm get values {feldera-release-name} --all -o yaml >> values.yaml where feldera-release-name is the name of your release. The value is usually feldera, unless the value has been configured during the installation process.
Configure custom database credentials
Instead of the insecure default DB credentials, you can supply your own custom database credentials.
-
Secret configuration file: create a file
feldera-db-secret.yamlwith custom database credentials.# Filename: feldera-db-secret.yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: feldera-db-secret
stringData:
.user: "..." # Fill in
.password: "..." # Fill in -
Create secret: with the configuration file, create the secret:
#kubectl create namespace feldera # If the namespace does not exist yet
kubectl apply -n feldera -f feldera-db-secret.yaml -
Specify secret during installation: in the
helminstallation command, set the following:--set felderaDatabaseSecretRef="feldera-db-secret"Note: it must be a new installation.
Connect to an external database service
You can connect to an external PostgreSQL database with the following steps:
- Secret configuration file: create a file
feldera-db-secret.yamlwith the.connection_url
# Filename: feldera-db-secret.yaml
apiVersion: v1
kind: Secret
type: Opaque
metadata:
name: feldera-db-secret
stringData:
.connection_url: "postgresql://username:password@db-name.cluster-name.region.rds.amazonaws.com/db_name?sslmode=require"
-
Create secret: with the configuration file, create the secret:
#kubectl create namespace feldera # If the namespace does not exist yet
kubectl apply -n feldera -f feldera-db-secret.yaml -
Optional: Add the TLS Certificate (
.pemfile) in a configmap:wget https://example.com/your-bundle.pem
kubectl create configmap postgres-pem -n feldera --from-file=postgresql-ca.pem=your-bundle.pemThis step is optional, if no certificate is provided feldera will use the system certificates (
ca-certificatespackage from Ubuntu 24.04 and the Amazon RDSglobal-bundle.pemfile) to validate the TLS connection.Note: If necessary, you can override the file (
postgresql-ca.pem) and configmap (postgres-pem) names by adjustingpostgresTlsCertificateFileandpostgresTlsConfigMapRefinvalues.yaml. -
Specify secret and external postgres configuration during installation: in the
helminstallation command, set the following:--set postgresExternal=true
--set felderaDatabaseSecretRef="feldera-db-secret"
--set postgresTlsConfigMapRef="postgres-pem"Note: it must be a new installation. If you skip step 3, you must not set the
postgresTlsConfigMapRefvariable.
Rotate the database password
To change the password of the bundled database, updating the secret alone isn't enough: Postgres only reads the password from the secret the first time it starts on an empty volume, and the Feldera components only read it when they start. So you change the password in Postgres itself, update the secret to match, and restart the components that connect to the database.
The steps below assume the release name feldera, the namespace feldera and the
secret feldera-db-secret from
Configure custom database credentials.
Adjust them if yours are different.
If you use the default feldera-db-insecure-secret, don't change that secret.
The Helm chart owns it, so the next helm upgrade sets the old password back.
Move to your own secret instead: in step 1 read the user and password from
feldera-db-insecure-secret, in step 3 create feldera-db-secret, and in step 4
run helm upgrade with your usual values and
--set felderaDatabaseSecretRef="feldera-db-secret" instead of the restart.
The upgrade restarts the components with the new secret.
-
Choose a new password: use only letters and digits. Feldera puts the password into a
postgresql://connection URL as is, so characters like@,:or/break the connection. Also save the current user and password, in case you need to go back.NEW_PASSWORD=$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 32)
DB_USER=$(kubectl get secret -n feldera feldera-db-secret -o jsonpath='{.data.\.user}' | base64 -d)
OLD_PASSWORD=$(kubectl get secret -n feldera feldera-db-secret -o jsonpath='{.data.\.password}' | base64 -d) -
Change the password in Postgres: inside the database pod,
psqlconnects over the local socket, so you don't need the old password. The statement goes in on stdin, which keeps the password out of the process list.printf "ALTER ROLE \"%s\" PASSWORD '%s';\n" "$DB_USER" "$NEW_PASSWORD" | \
kubectl exec -i -n feldera feldera-db-0 -- sh -c 'psql -U "$POSTGRES_USER" -d postgres -v ON_ERROR_STOP=1'It should print
ALTER ROLE. From now on, new connections with the old password fail. Connections that are already open continue to work, so do the next steps right away. -
Update the secret:
kubectl create secret generic feldera-db-secret -n feldera \
--from-literal=.user="$DB_USER" --from-literal=.password="$NEW_PASSWORD" \
--dry-run=client -o yaml | kubectl apply -f -Also update the place the secret comes from, for example your
feldera-db-secret.yamlfile or your GitOps repository. If someone applies the old value again later, the components can't log in after their next restart.If the secret is managed by the External Secrets Operator, update the value in your secret manager instead. The operator only syncs at its
refreshInterval, so force a sync and make sure the status isSecretSyncedbefore step 4:kubectl annotate externalsecret -n feldera feldera-db-secret force-sync=$(date +%s) --overwrite
kubectl get externalsecret -n feldera feldera-db-secret -
Restart the Feldera components:
kubectl rollout restart -n feldera deployment/feldera-api-server deployment/feldera-kubernetes-runner statefulset/feldera-compiler-server
kubectl rollout status -n feldera deployment/feldera-api-server
kubectl rollout status -n feldera deployment/feldera-kubernetes-runner
kubectl rollout status -n feldera statefulset/feldera-compiler-serverIf compiler autoscaling is enabled, also restart
deployment/feldera-compiler-artifact-server. You don't need to restart the database pod. If it restarts later, it keeps the new password. -
Check: all pods should be
Running, and the API server logs should show no authentication errors. Your pipelines keep running during the rotation.
If step 2 fails, nothing has changed yet, and the components still use the old password.
If step 3 or 4 fails, for example a pod stays in CrashLoopBackOff with
authentication errors, go back to the old password: run steps 2 and 3 again with
"$OLD_PASSWORD" in place of "$NEW_PASSWORD", then do step 4.
If you use an external database, change the password there, update
.connection_url in the secret, and proceed to step 4.
Feldera installation overview
Services:
$ kubectl get svc -n feldera
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
feldera-kubernetes-runner ClusterIP 10.43.175.228 <none> 8080/TCP 5m10s
feldera-api-server ClusterIP 10.43.176.120 <none> 8080/TCP 5m10s
feldera-db ClusterIP 10.43.60.190 <none> 5431/TCP 5m10s
feldera-compiler-server ClusterIP 10.43.60.125 <none> 8085/TCP 5m10s
Pods:
$ kubectl get pods -n feldera
NAME READY STATUS RESTARTS AGE
feldera-db-0 1/1 Running 0 5m31s
feldera-kubernetes-runner-6447b8f56d-86j4w 1/1 Running 0 5m31s
feldera-compiler-server-0 1/1 Running 0 5m31s
feldera-api-server-c546499bc-wdpkm 1/1 Running 0 5m31s
StatefulSets:
$ kubectl get sts -n feldera
NAME READY AGE
feldera-db 1/1 5m41s
feldera-compiler-server 1/1 5m41s
Deployments:
$ kubectl get deployments -n feldera
NAME READY UP-TO-DATE AVAILABLE AGE
feldera-kubernetes-runner 1/1 1 1 5m55s
feldera-api-server 1/1 1 1 5m55s
Persistent volume claims:
$ kubectl get pvc -n feldera
NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
db-storage-feldera-db-0 Bound pvc-a5acb4ef-1d3c-4773-ad42-528657f11c94 20Gi RWO local-path 6m11s
compiler-storage-feldera-compiler-server-0 Bound pvc-07369993-c20a-4f8a-abd1-52bf3be413c3 20Gi RWO local-path 6m11s
Uninstallation
If you installed Feldera in its own dedicated namespace,
the most thorough way to uninstall Feldera is to delete the entire namespace:
kubectl delete namespace feldera
If you wish to preserve the namespace, it can be uninstalled through
the usual helm method:
helm uninstall -n feldera feldera
This does not delete the persistent volumes, which need to be deleted separately:
kubectl get pvc -n feldera
kubectl delete pvc -n feldera db-storage-feldera-db-0
kubectl delete pvc -n feldera compiler-storage-feldera-compiler-server-0
kubectl get pvc -n feldera
Troubleshooting
Incorrect license
If an incorrect account id and/or license key was provided, the kubernetes-runner will fail to start:
$ kubectl get pods -n feldera
NAME READY STATUS RESTARTS AGE
feldera-db-0 1/1 Running 0 2m34s
feldera-compiler-server-0 1/1 Running 0 2m34s
feldera-kubernetes-runner-854446fb84-rg66z 0/1 CrashLoopBackOff 1 (9s ago) 2m34s
feldera-api-server-7bb757f685-jwn5v 1/1 Running 0 2m34s
... and an explanation will be visible in its log:
$ kubectl logs -n feldera deployment/feldera-kubernetes-runner
...
FAIL: license verification failed: a valid license is required for the Enterprise version of Feldera. Please contact Feldera support (support@feldera.com) to resolve this issue.
...
To resolve this, provide a correct account id and license key
during the helm installation.
If you do not have a license, please reach out to us at support@feldera.com.