From fa68422767eaf5d3e733a4d81cc6e2760845185e Mon Sep 17 00:00:00 2001 From: dreger1997 Date: Thu, 23 Oct 2025 17:04:53 +0200 Subject: [PATCH 1/3] added docs to deploy helm chart --- .../install-deploy/deploying-with-helm.md | 405 ++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 website/docs/install-deploy/deploying-with-helm.md diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md new file mode 100644 index 0000000000..bdc0332b53 --- /dev/null +++ b/website/docs/install-deploy/deploying-with-helm.md @@ -0,0 +1,405 @@ +--- +title: "Deploying with Helm Charts" +sidebar_position: 5 +--- + +# Deploying with Helm Charts + +This page provides instructions for deploying a Fluss cluster on Kubernetes using Helm charts. The chart creates a distributed streaming storage system with CoordinatorServer and TabletServer components. + +## Prerequisites + +Before installing the Fluss Helm chart, ensure you have: + +- Kubernetes +- Helm +- A running ZooKeeper ensemble (required for coordination) +- Sufficient cluster resources for the deployment +- **For Local Development**: Minikube and Docker (see [Local Development with Minikube](#local-development-with-minikube)) + +## Supported Versions + +| Component | Minimum Version | Recommended Version | +|-----------|----------------|-------------------| +| [Kubernetes](https://kubernetes.io) | v1.19+ | v1.25+ | +| [Helm](https://helm.sh) | v3.8.0+ | v3.18.6+ | +| [ZooKeeper](https://zookeeper.apache.org) | v3.6+ | v3.8+ | +| [Apache Fluss](https://fluss.apache.org/docs/) (Container Image) | v0.8-SNAPSHOT | v0.8-SNAPSHOT | +| [Minikube](https://minikube.sigs.k8s.io) (Local Development) | v1.25+ | v1.32+ | +| [Docker](https://docs.docker.com/) (Local Development) | v20.10+ | v24.0+ | + +## Installation + +### Running Fluss locally with Minikube + +For local testing and development, you can deploy Fluss on Minikube. This is ideal for development, testing, and learning purposes. + +#### Prerequisites + +- Docker container runtime +- At least 4GB RAM available for Minikube +- At least 2 CPU cores available + +#### Start Minikube + +```bash +# Start Minikube with recommended settings for Fluss +minikube start + +# Verify cluster is ready +kubectl cluster-info +``` + +#### Configure Docker Environment (Optional) + +To build images directly in Minikube you need to configure the Docker CLI to use Minikube's internal Docker daemon: + +```bash +# Configure shell to use Minikube's Docker daemon +eval $(minikube docker-env) +``` + +To build custom images please refer to [Custom Image Configuration](#custom-image-configuration) + +### Installing the chart on a cluster + +This installation process is generally working for a distributed Kubernetes cluster or a Minikube setup. + +### Step 1: Deploy ZooKeeper (Optional if ZooKeeper is existing) + +To start Zookeeper use Bitnami’s chart or your own deployment. If you have an existing Zookeeper cluster, you can skip this step. Example with Bitnami’s chart: + +```bash +# Add Bitnami repository +helm repo add bitnami https://charts.bitnami.com/bitnami +helm repo update + +# Deploy ZooKeeper +helm install zk bitnami/zookeeper +``` +### Step 2: Deploy Fluss + +#### Install from Helm repo + +```bash +# TODO: Add chart to Helm repo. +helm repo add fluss https://charts.fluss.apache.org +helm repo update +helm install helm-repo/fluss +``` + +#### Install from Local Chart + +```bash +helm install fluss ./docker/helm +``` + +#### Install with Custom Values + +You can customize the installation by providing your own `values.yaml` file or setting individual parameters via the `--set` flag. Using a custom values file: + +```bash +helm install fluss ./docker/helm -f my-values.yaml +``` + +Or for example to change the ZooKeeper address via the `--set` flag: + +```bash +helm install fluss ./docker/helm \ + --set configurationOverrides.zookeeper.address=:2181 +``` + +### Cleanup + +```bash +# Uninstall Fluss +helm uninstall fluss + +# Uninstall ZooKeeper +helm uninstall zk + +# Delete PVCs +kubectl delete pvc -l app.kubernetes.io/name=fluss + +# Stop Minikube +minikube stop + +# Delete Minikube cluster +minikube delete +``` + +## Architecture Overview + +The Fluss Helm chart deploys the following Kubernetes resources: + +### Core Components +- **CoordinatorServer**: 1x StatefulSet with Headless Service for cluster coordination +- **TabletServer**: 3x StatefulSet with Headless Service for data storage and processing +- **ConfigMap**: Configuration management for server.yaml settings +- **Services**: Headless services providing stable pod DNS names + +### Optional Components +- **PersistentVolumes**: Data persistence when `persistence.enabled=true` + + +### Step 3: Verify Installation + +```bash +# Check pod status +kubectl get pods -l app.kubernetes.io/name=fluss + +# Check services +kubectl get svc -l app.kubernetes.io/name=fluss + +# View logs +kubectl logs -l app.kubernetes.io/component=coordinator +kubectl logs -l app.kubernetes.io/component=tablet +``` + +## Configuration Parameters + +The following table lists the configurable parameters of the Fluss chart and their default values. + +### Global Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `nameOverride` | Override the name of the chart | `""` | +| `fullnameOverride` | Override the full name of the resources | `""` | + +### Image Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `image.registry` | Container image registry | `""` | +| `image.repository` | Container image repository | `fluss` | +| `image.tag` | Container image tag | `0.8-SNAPSHOT` | +| `image.pullPolicy` | Container image pull policy | `IfNotPresent` | +| `image.pullSecrets` | Container image pull secrets | `[]` | + +### Application Configuration + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `appConfig.internalPort` | Internal communication port | `9123` | +| `appConfig.externalPort` | External client port | `9124` | + +### Fluss Configuration Overrides + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `configurationOverrides.default.bucket.number` | Default number of buckets for tables | `3` | +| `configurationOverrides.default.replication.factor` | Default replication factor | `3` | +| `configurationOverrides.zookeeper.path.root` | ZooKeeper root path for Fluss | `/fluss` | +| `configurationOverrides.zookeeper.address` | ZooKeeper ensemble address | `zk-zookeeper.{{ .Release.Namespace }}.svc.cluster.local:2181` | +| `configurationOverrides.remote.data.dir` | Remote data directory for snapshots | `/tmp/fluss/remote-data` | +| `configurationOverrides.data.dir` | Local data directory | `/tmp/fluss/data` | +| `configurationOverrides.internal.listener.name` | Internal listener name | `INTERNAL` | + +### Persistence Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `persistence.enabled` | Enable persistent volume claims | `false` | +| `persistence.size` | Persistent volume size | `1Gi` | +| `persistence.storageClass` | Storage class name | `nil` (uses default) | + +### Resource Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `resources.coordinatorServer.requests.cpu` | CPU requests for coordinator | Not set | +| `resources.coordinatorServer.requests.memory` | Memory requests for coordinator | Not set | +| `resources.coordinatorServer.limits.cpu` | CPU limits for coordinator | Not set | +| `resources.coordinatorServer.limits.memory` | Memory limits for coordinator | Not set | +| `resources.tabletServer.requests.cpu` | CPU requests for tablet servers | Not set | +| `resources.tabletServer.requests.memory` | Memory requests for tablet servers | Not set | +| `resources.tabletServer.limits.cpu` | CPU limits for tablet servers | Not set | +| `resources.tabletServer.limits.memory` | Memory limits for tablet servers | Not set | + + +## Advanced Configuration + +### Custom ZooKeeper Configuration + +For external ZooKeeper clusters: + +```yaml +configurationOverrides: + zookeeper.address: "zk1.example.com:2181,zk2.example.com:2181,zk3.example.com:2181" + zookeeper.path.root: "/my-fluss-cluster" +``` + +### Network Configuration + +The chart automatically configures listeners for internal cluster communication and external client access: + +- **Internal Port (9123)**: Used for inter-service communication within the cluster +- **External Port (9124)**: Used for client connections + +Custom listener configuration: + +```yaml +appConfig: + internalPort: 9123 + externalPort: 9124 + +configurationOverrides: + bind.listeners: "INTERNAL://0.0.0.0:9123,CLIENT://0.0.0.0:9124" + advertised.listeners: "CLIENT://my-cluster.example.com:9124" +``` + +### Storage Configuration + +Configure different storage backends: + +```yaml +configurationOverrides: + data.dir: "/data/fluss" + remote.data.dir: "s3://my-bucket/fluss-data" +``` + +## Upgrading + +### Upgrade the Chart + +```bash +# Upgrade to a newer chart version +helm upgrade fluss ./docker/helm + +# Upgrade with new configuration +helm upgrade fluss ./docker/helm -f values-new.yaml +``` + +### Rolling Updates + +The StatefulSets support rolling updates. When you update the configuration, pods will be restarted one by one to maintain availability. + +## Custom Container Images + +### Building Custom Images + +To build and use custom Fluss images: + +1. Build the project with Maven: +```bash +mvn clean package -DskipTests +``` + +2. Build the Docker image: +```bash +# Copy build artifacts +cp -r build-target/* docker/build-target/ + +# Build image +cd docker +docker build -t my-registry/fluss:custom-tag . +``` + +3. Use in Helm values: +```yaml +image: + registry: my-registry + repository: fluss + tag: custom-tag + pullPolicy: Always +``` + +## Monitoring and Observability + +### Health Checks + +The chart includes liveness and readiness probes: + +```yaml +livenessProbe: + tcpSocket: + port: 9124 + initialDelaySeconds: 10 + periodSeconds: 3 + failureThreshold: 100 + +readinessProbe: + tcpSocket: + port: 9124 + initialDelaySeconds: 10 + periodSeconds: 3 + failureThreshold: 100 +``` + +### Logs + +Access logs from different components: + +```bash +# Coordinator logs +kubectl logs -l app.kubernetes.io/component=coordinator -f + +# Tablet server logs +kubectl logs -l app.kubernetes.io/component=tablet -f + +# Specific pod logs +kubectl logs coordinator-server-0 -f +kubectl logs tablet-server-0 -f +``` + +## Troubleshooting + +### Common Issues + +#### Pod Startup Issues + +**Symptoms**: Pods stuck in `Pending` or `CrashLoopBackOff` state + +**Solutions**: +```bash +# Check pod events +kubectl describe pod + +# Check resource availability +kubectl describe nodes + +# Verify ZooKeeper connectivity +kubectl exec -it -- nc -zv 2181 +``` + +#### Image Pull Errors + +**Symptoms**: `ImagePullBackOff` or `ErrImagePull` + +**Solutions**: +- Verify image repository and tag exist +- Check pull secrets configuration +- Ensure network connectivity to registry + + +#### Connection Issues + +**Symptoms**: Clients cannot connect to Fluss cluster + +**Solutions**: +```bash +# Check service endpoints +kubectl get endpoints + +# Test network connectivity +kubectl exec -it -- nc -zv 9124 + +# Verify DNS resolution +kubectl exec -it -- nslookup +``` + +### Debug Commands + +```bash +# Get all resources +kubectl get all -l app.kubernetes.io/name=fluss + +# Check configuration +kubectl get configmap fluss-conf-file -o yaml + + +# Get detailed pod information +kubectl get pods -o wide -l app.kubernetes.io/name=fluss +``` + From daab98c46dfdebbdde3c6e97e497cc200e6003e2 Mon Sep 17 00:00:00 2001 From: dreger1997 Date: Tue, 28 Oct 2025 06:24:36 +0100 Subject: [PATCH 2/3] fixed links in docs and added FLUSS_VERSION var --- website/docs/install-deploy/deploying-with-helm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md index bdc0332b53..61d47c7007 100644 --- a/website/docs/install-deploy/deploying-with-helm.md +++ b/website/docs/install-deploy/deploying-with-helm.md @@ -15,7 +15,7 @@ Before installing the Fluss Helm chart, ensure you have: - Helm - A running ZooKeeper ensemble (required for coordination) - Sufficient cluster resources for the deployment -- **For Local Development**: Minikube and Docker (see [Local Development with Minikube](#local-development-with-minikube)) +- **For Local Development**: Minikube and Docker (see [Local Development with Minikube](#running-fluss-locally-with-minikube)) ## Supported Versions @@ -24,7 +24,7 @@ Before installing the Fluss Helm chart, ensure you have: | [Kubernetes](https://kubernetes.io) | v1.19+ | v1.25+ | | [Helm](https://helm.sh) | v3.8.0+ | v3.18.6+ | | [ZooKeeper](https://zookeeper.apache.org) | v3.6+ | v3.8+ | -| [Apache Fluss](https://fluss.apache.org/docs/) (Container Image) | v0.8-SNAPSHOT | v0.8-SNAPSHOT | +| [Apache Fluss](https://fluss.apache.org/docs/) (Container Image) | $FLUSS_VERSION$ | $FLUSS_VERSION$ | | [Minikube](https://minikube.sigs.k8s.io) (Local Development) | v1.25+ | v1.32+ | | [Docker](https://docs.docker.com/) (Local Development) | v20.10+ | v24.0+ | @@ -59,7 +59,7 @@ To build images directly in Minikube you need to configure the Docker CLI to use eval $(minikube docker-env) ``` -To build custom images please refer to [Custom Image Configuration](#custom-image-configuration) +To build custom images please refer to [Custom Container Images](#custom-container-images). ### Installing the chart on a cluster @@ -173,7 +173,7 @@ The following table lists the configurable parameters of the Fluss chart and the |-----------|-------------|---------| | `image.registry` | Container image registry | `""` | | `image.repository` | Container image repository | `fluss` | -| `image.tag` | Container image tag | `0.8-SNAPSHOT` | +| `image.tag` | Container image tag | `$FLUSS_VERSION$` | | `image.pullPolicy` | Container image pull policy | `IfNotPresent` | | `image.pullSecrets` | Container image pull secrets | `[]` | From 3a427574a967d221efd0b500b05897394f4f15f1 Mon Sep 17 00:00:00 2001 From: Jark Wu Date: Sun, 2 Nov 2025 17:00:41 +0800 Subject: [PATCH 3/3] Jark's modification --- .../install-deploy/deploying-with-helm.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md index 61d47c7007..a331343639 100644 --- a/website/docs/install-deploy/deploying-with-helm.md +++ b/website/docs/install-deploy/deploying-with-helm.md @@ -13,9 +13,13 @@ Before installing the Fluss Helm chart, ensure you have: - Kubernetes - Helm -- A running ZooKeeper ensemble (required for coordination) -- Sufficient cluster resources for the deployment -- **For Local Development**: Minikube and Docker (see [Local Development with Minikube](#running-fluss-locally-with-minikube)) +- **For Local Development**: Minikube and Docker (see [Local Development with Minikube](#running-fluss-locally-with-minikube)) + +:::note +A Fluss cluster deployment requires a running ZooKeeper ensemble. To provide flexibility in deployment and enable reuse of existing infrastructure, +the Fluss Helm chart does not include a bundled ZooKeeper cluster. If you don’t already have a ZooKeeper running, +the installation documentation provides instructions for deploying one using Bitnami’s Helm chart. +::: ## Supported Versions @@ -82,8 +86,7 @@ helm install zk bitnami/zookeeper #### Install from Helm repo ```bash -# TODO: Add chart to Helm repo. -helm repo add fluss https://charts.fluss.apache.org +helm repo add fluss https://downloads.apache.org/incubator/fluss/helm-chart helm repo update helm install helm-repo/fluss ``` @@ -91,7 +94,7 @@ helm install helm-repo/fluss #### Install from Local Chart ```bash -helm install fluss ./docker/helm +helm install fluss ./helm ``` #### Install with Custom Values @@ -99,13 +102,13 @@ helm install fluss ./docker/helm You can customize the installation by providing your own `values.yaml` file or setting individual parameters via the `--set` flag. Using a custom values file: ```bash -helm install fluss ./docker/helm -f my-values.yaml +helm install fluss ./helm -f my-values.yaml ``` Or for example to change the ZooKeeper address via the `--set` flag: ```bash -helm install fluss ./docker/helm \ +helm install fluss ./helm \ --set configurationOverrides.zookeeper.address=:2181 ``` @@ -135,7 +138,7 @@ The Fluss Helm chart deploys the following Kubernetes resources: ### Core Components - **CoordinatorServer**: 1x StatefulSet with Headless Service for cluster coordination - **TabletServer**: 3x StatefulSet with Headless Service for data storage and processing -- **ConfigMap**: Configuration management for server.yaml settings +- **ConfigMap**: Configuration management for `server.yaml` settings - **Services**: Headless services providing stable pod DNS names ### Optional Components @@ -265,10 +268,10 @@ configurationOverrides: ```bash # Upgrade to a newer chart version -helm upgrade fluss ./docker/helm +helm upgrade fluss ./helm # Upgrade with new configuration -helm upgrade fluss ./docker/helm -f values-new.yaml +helm upgrade fluss ./helm -f values-new.yaml ``` ### Rolling Updates @@ -289,7 +292,7 @@ mvn clean package -DskipTests 2. Build the Docker image: ```bash # Copy build artifacts -cp -r build-target/* docker/build-target/ +cp -r build-target/* docker/fluss/build-target # Build image cd docker